#1

EDIT July 26, 2018: You can access the latest docs and cheatsheet for the latest version of teletype here, and can learn more about the toolchain used to build the docs in the teletype repo’s readme. It is set up so that writing documentation can be done in Markdown, and utilizes pandoc to generate both webpage and PDF versions of the documentation. Bug reports of issues and enhancements are welcome and encouraged in github.

Hey everyone,

This thread is all about firming up the user experience of the new documentation that was part of the Teletype 2.0 release. Based on previous discussion, the goal here is simplicity and not trying to boil the ocean with big changes. That being said, I feel that any/all discussion about how to make the UX of the docs the best they can be is welcome, we might just have to push some of the implementation of that stuff out into 2.1 or future releases.

I figure we could work off of the docsiteEnhancements branch of my fork. Any PRs can be made to that branch on my fork, and then we can see about merging that branch into the monome/teletype repo master branch after we are ready to go live. I went ahead and opened a PR for that. If anyone would like to contribute but needs help with either the dependencies or the github workflow, don’t hesitate to reach out!

I did some trawling through the current site, and propose some small improvements that I think could benefit people using the docs. Feedback is welcome and encouraged (and please let me know if you think one of my proposed enhancements needs rethinking–I will not take offense)!

UX Enhancements
This stuff is pretty straight-forward and I’m happy to work through these things…definitely open to discussion and others contributions though!

  • DONE stick TOC on left hand side of window
    • for mobile, hide behind hamburger icon (I just have the bar showing up for all screen widths–seemed sensible)

Screen Shot 2017-07-23 at 10.18.18 PM.png2410×2162 549 KB

  • DONE-ish better responsiveness of wide tables (see Variables table in OPs and MODs section
    • currently, wide tables overflow the horizontal width of smaller screens.
    • I’ve updated things to fill better across screen sizes. The tables are still not great, but they are usable.
  • DONE target=“_blank” on links off of docs
    • In past projects I’ve worked on, we’ve decided that links outside of the content you are currently looking at should open in a new tab so as to prevent context switching.
  • DONE anchor link next to doc sections (allowing for linking of specific sections of the docs)
    • this shouldn’t be difficult because it’s already reflected in the URL as a hash
  • NOT CHANGED Quantization scale content is repeated
    • It’s fine that it’s repeated visually, need to see if the content is repeated in the repo…could lead to change drift
  • NOT CHANGED Include footnote sources under relevant sections (rather than at the bottom of the docs)
    • Not a big deal…if this isn’t a 5-minute fix, I’ll probably push this one out.
  • DONE Update .editorconfig
  • Explore the ability to export each section to it’s own .HTML file (not sure if that’s possible).
  • DONE Update h1 and h3-in-code-element css
  • NOT CHANGED Enhancements to TOC
    • make full width (and click-link-to-close) for more narrow browser widths
    • highlight when hovering over a particular nav element in the TOC.

Wording Change Proposals
This stuff relates to reorganizing content/wording. These proposals are more opinionated on my part, so I’d like to get some feedback before making these changes.

  • Consider renaming “Advanced” section to something like “Tips and Tricks” or “Best Practices for writing Teletype Scripts”
  • Consider aggregating “What’s new?” and Changelog sections

Content still needed (I need help here)
There are a couple of things that are missing, as mentioned by @sam. If anyone wants to craft these and PR them (or just post what they should be here and I can add them into Github), that would be much appreciated.

  • The intro section (cc @tehn)
    • Can be pretty much copied over verbatim from http://monome.org/docs/modular/teletype/
    • Would probably be good to include a link to the Telex module repo in the installation section
    • May want to consider updating links in the introduction section (the command/key PDFs are out of date, and the “Scenes shipped with version 1.0 should probably be changed to “Default scenes” or something)
  • A contribution section
    • This could be really short and just link to the github repo and say something along the lines of “Information about contributing to the Teletype firmware, as well as submitting bugs and feature requests can be found in the Teletype github repo”
    • Could also be good to include licensing information here
  • NEW Teletype Studies
    • Content is already in markdown, wouldn’t be difficult to add to the docs.
  • NEW Community scenes

I’ve been thinking about this one as well. It’d be really cool if there was a tool built for sharing/viewing community-generated scenes (and also another tool for interactively crafting a flashdrive for populating a Teletype with scenes from a library on the computer), but for minimally-viable, I like the idea of some download links, and a manual process of adding them to the docs is fine for the time being.

@bpcmusic, something you’d be interested in?

Design changes
Design (typography/colors/etc.) is a little outside of my wheelhouse. I feel like what we have works great, but if any designers want to take a hand at crafting a typography style guide, we can discuss here and I’d be happy to help with implementing the CSS to make that happen.

After we figure these things out, we can talk about the ops side of things of putting this on the website.

11 Likes
#2

Also, @sam, when you get a chance (no rush), could you confirm that what I’m doing with the custom template is cool with you? See this commit. I took the default template here and just added some classes to surround the content (necessary for CSS targeting to get the TOC side-by-side with the content).

2 Likes
#3

:+1:

Only have one hand free at the moment… will pull your changes locally and try to give more feedback later…

Absolutely! It looks like you’ve got a good handle on how pandoc likes to work, and using a custom template is 100% the right way to go.

Don’t be afraid to make more changes too, especially if you’re willing to take responsibility for them. (Feel free to get rid of the html5 shim too, I doubt we care about <= IE9 and I’m not a massive fan of Cloudflare.)

The missing docs are already in Markdown format, see here:

The “Teletype studies” files are there already too.

The relevant content from the intro probably needs some rewording to make it fit, and both it and the studies need updating to reflect 2.0 changes.

It’s possible that either @GoneCaving or @tambouri might consider helping with those… they helped loads on the ops.

We could go with using monome.github.io for generated docs and using the corresponding GitHub infrastructure and workflow. That might be a lot easier for @tehn to administrate.

I’m up for any/all changes to the wording and organisation of the document, most of the stuff I did was in a hurry. My suggestion would be to try and get the intro and the Teletype studies added in first though, and then try to step back and take stock.

The other idea I’d had was to try to build up a library of Teletype scenes. On the beta thread there was some talk about new default scenes, personally I think that default scenes are much more useful for brand new Teletypes than firmware upgrades. What I’d love is a community zip archive of scenes that I can load individually. But in order to get your scene added to the archive you’d also have to contribute a little write up for the docs outlining how it works and what it does (and anything else you’d care to share).

4 Likes
#4

Happy to help out once I get back from vacation (mid-Aug).

I agree with this (though also happy to expand on the documentation if given a scene and a rough outline). I think it would be particularly helpful to also add a Teletype study lesson on the TXi/o and and scene or two that shows the possibilities of the expanders.

1 Like
#5

@GoneCaving @sam I’ve updated the original post with the new ideas, thank y’all!

And thanks for taking a look and the feedback on the code @sam

#6

i’d be happy to help out w/ some more documentation! let me know when’s a good time and place to jump in

1 Like
#7

Thanks! Anytime on the stuff under “Content Still Needed”–I’ll be working mostly in the utlis/ directory, so there’s probably not much of a chance of conflict (and if there is, nbd, we can figure it out).

I think for now it’d be fine for us to copy the content from the docs repo, and then we can figure out how to consolidate based on what @tehn thinks.

#8

oh, this is fantastic! thank you for the efforts.

it’d be pretty great to effectively do a full refresh of http://monome.org/docs/modular/teletype/ but that may be a tall order. certainly feel free to pull any content from there to integrate into the v2 docs.

i’m not certain the existing CSS will fulfill all of the UX wishes as stated-- though i’m also happy to update the CSS on the main docs site.

furthermore i’d be incredibly grateful for a proofreader, to spot new inconsistencies in the teletype studies. perhaps each study also needs a short addendum, a quick list of related version 2 topics/ops/etc to check out.

1 Like
#9

Happy to help!

My initial thinking is that after we finish the improvements here, the static files living in teletype/utils and teletype/docs would be what you get when you go to http://monome.org/docs/modular/teletype/ but happy to do whatever.

We can figure out the syncing between the two repos (the docs one and the teletype one) and the build pipeline (the travis side of things) after we get all the content/updates figured out.

The pandoc html template currently builds a full HTML doc, but I’m pretty sure we can change that (or build a second html target) to just be a “partial” that fits within the current docs infrastructure (haven’t looked into that side of things yet–I’ll make sure that’s cool).

I also think we could pretty easily “namespace” the styling for the teletype stuff generated by pandoc so that we don’t have conflicts with the rest of the monome docs css.

#10

if it seems like a helpful place to start i can work on the intro v2

1 Like
#11

Absolutely!

Yeah. They are doubled.

Didn’t want folks to have to hunt for them - but perhaps there is a better way. :slight_smile:

Thanks for your efforts on this!!

1 Like
#12

It would be great if we could split each section into separate HTML files, but I’m unsure how internal links will work then. Maybe we can fake it with javascript to make navigation easier. It will be a tricky balancing act to keep both the PDF and HTML docs as 1st class targets.

We should probably add entries to the .editorconfig file for HTML and CSS (and Python) too.

1 Like
#13

Hi!

I’m a long time forum follower and wanted to express my gratitude for everyone’s contributions updating the teletype documentation. Shout out to @jlmitch5 for initiating the topic and @tehn for giving the community a starting point. This is the type of communal collaboration that I’ve enjoyed reading over the years.

Admission… I don’t have a teletype “yet”. Actually I don’t even have a proper euro rack case but I’ve got a few standalone synths that accept and send cv/gate voltages. I still haven’t figured out if the teletype will work for my setup or how I think it can be used (based on online video demos).

As a new user, the updated documentation will help me immensely. I also really like the idea of a community scene exchange! It would be helpful if updated download links were kept in the same document/topic with a comment/feedback section. I’m curious to see what the community develops.

Cheers!

2 Likes
#14

Made some progress today with the list.

I’m not sure how you’d split things out to multiple files with Pandoc. As far as I can tell, all the generated content goes into the $body$ target of the template. If you see anything online about it/want to look into that, happy to take it on!

I could see this becoming an issue too. Right now, I’m trying to make sure the stuff going into the html template file are strictly presentational.

Not something I’ve done in the past, but I’ll add it to my list of things, doesn’t seem like it’d be difficult.

1 Like
#15

Appreciate the kind words @n8sum, happy to help! I will say, @sam did all the heavy lifting of getting the docs together (not to mention the actual firmware work).

2 Likes
#16

Alrightee, now that I’ve finished most of the front-end focused enhancements, it’d be great to get some design feedback.

Thus far, I’ve added:

  • A toggle-able table of contents to the left of the screen.
    • It defaults to open for browsers with width > 700px, and closed for those that are more narrow (i.e.: mobile)
  • Some improvements to making tables more readable when browser widths are more narrow
  • External links should open in a new tab, internal links should not
  • I’ve added the ability to click any header and copy a link to that specific section to the clipboard.

If going through the dependency install/build process is too daunting, here’s the latest html file (with embedded css/javascript). Just download and open in a browser to see it.

(EDIT: old) with_ux_enhancements_teletype.html (443.0 KB)

LATEST: teletype.html (527.0 KB)

4 Likes
#17

Looking really good!

I’ve pulled the changes and tested building locally.

A few small points…

  • I’ve mentioned it on the relevant changes, but did you mean to alter the table headers in the Markdown files?

  • Looks like <code> tags inside <h3> tags are rendering a bit weird.

  • I’m wondering if the <h1> tags have enough impact?

  • Also, would it be better to have a modal table of contents with smaller screens? (Assuming that isn’t too much work).

Hope that’s helpful.

1 Like
#18

Thanks for the feedback!

Those changes were made to better “fit” the contents within the columns (for example, one of the tables didn’t show any aliases so I shrunk that column a bit and made the column for OP (set) a little wider. Happy to change those back or adjust further.

I can bump h1 a little and check out the h3-in-code issue.

I’d rather not introduce a library dependency, and I don’t really want to roll my own modal implementation for this. Also I’m not sure that I think that a modal is the right ux pattern for this sort of thing. They are typically better for things like confirmation dialogs, where there isn’t a lot of “options” for the user to interact with. At least that’s what the ux justification from a designer in a previous project worked on (and makes sense to me).

That being said, at less than a certain width (take 700px for example), it’s a little sloppy to show the docs at all, because when the TOC is open, there’s only a couple hundred pixels width for the content to display.

I’ve got an idea for fixing that, I’ll ping you when that’s ready.

1 Like
#19

Just a note that I’m a little busy right now with other things, but will be back to working on this Monday. Keep the feedback coming (it’s very helpful!)

1 Like
#20

Ah, didn’t realise that affected HTML output too. Just make sure that the PDFs render okay.

Good call, the Javascript ecosystem generally makes me feel sad, let’s avoid it!

2 Likes