Teletype docs enhancements (redesign in progress)

[scanner_darkly]

one of the problems is that we actually have 3 op types - some are just get, some are just set and some are get/set (and i just realized there is an existing inconsistency right in the image above - G.DIM level is a set only but is shown in the get cell instead of the set cell which could create confusion). i think there might also be cases where an op that could support both get/set only supports get (just because set was never implemented). so i would probably explicitly list all versions for each op but yeah, maybe we could omit “get/set” from the description language?

edit: i guess i’m contradicting myself above, if we have set only ops we need to make it clear in the description…

[Leverkusen]

I just found this and wanted to give a short feedback how the new layout works and feels to me on a macbook w/ safari:

First of all I appreciate the effort put into this! As the teletype development progresses the documentation gets more important to make it easier to follow and keep it accessible.

1. To me the menu on the left feels a bit too wide and attracts the focus of sight a lot. I looks great from a design point of view but also takes a lot of screen space. My eyes tend to focus to the left all the time and I have to deliberately refocus them to the right again to follow the content which feels a bit strange. I use the menu a lot when looking something up so closing and opening it again feels uncomfortable. It might be just me but I already have a sidebar constantly open with links in safari.

I understand that this is related to the new design of monome.org and I have to admit that I had the same feeling there. It looks great at a first glance, but when I start scrolling the main content it seems to be weighted to the right side of the screen in an irritating way, a bit like reading a right-aligned text while on the left side a wide part of the design is doing nothing.

2. When I alter the window size from full screen to, say, half screen the automatic line break does not always work right and a part of the text gets lost. Like this:

3. In the OP menu some external devices are called by their full manufacturer name (ER-301, TELEX) and some are not (just friends, w/). I prefer the short forms and I am sure anyone, who visits the docs for reference to them knows what is meant. Also this would allow to make the menu a bit smaller and get rid of line breaks.

4. Did I understand it right that what looks like widely spaced list that needs a lot of scrolling should really be a table that just got corrupted somehow at the moment?

5. regarding the discussion about the alphabetical list: I would prefer to have one for reference as I find it a bit cumbersome when I want to check a syntax and have to search for the OP first.

I hope my feedback will be seen as helpful and does contribute to the process.

[sam]

one of the problems is that we actually have 3 op types - some are just get, some are just set and some are get/set (and i just realized there is an existing inconsistency right in the image above - G.DIM level is a set only but is shown in the get cell instead of the set cell which could create confusion).

The problem is that the get/set nomenclature is misleading.

Really in the code there is only “get” or “get/set”, and those names are just a hang over from the first versions of the code. In hindsight I should have changed the names back when I did 2.0, but it was only when others started contributing that I realised how confusing they were.

Better names would be:

• normal: OPs that always do the same thing regardless
• normal/set (or even normal/head): OPs that have 2 behaviours depending on where they are, if they are in the first position in a sub-command they can optionally take an extra value, typically this is used for things that have read/write behaviour.

So in your example G.DIM should be in the first column as it only has normal behaviour.

Perhaps we should renamed the “OP (set)” column to something else? “OP (special)” maybe? (As in this is the ‘special’ form of the OP.)

[alanza]

I prefer “head” to “special”, as it bakes in what is different about these ops into the description

[Olivier]

Amazing - thanks for the detailed feedback. This is precisely the kind of stuff I’m looking for, design-wise.

To your first point, I agree that we can improve the overall layout. In fact, small tweaks should go a long way. As a test, I just played around in dev tools to reduce the width of the menu, increase the max-width of the main content area and bump the font-size up a point – just those things alone feel better to me. What do you think?

[Leverkusen]

I think it looks more like a document that is fun to read and navigate through - seems much better weighted to me.

[jlmitch5]

Like the new mockup, and thank you for the feedback @Leverkusen!

One tweak I would want to consider @olivier is tamping back the max width of the content area a little bit. Some of the line lengths there look like they might be a bit long. I know there’s some “best practice ux max width of text” guidelines but not sure what they are.

Keep the feedback coming! Gonna probably wait a week or so before taking a more thorough second pass and opening a PR

[PacificNorthWes]

Traditionally they recommend 80 characters, but that’s not a hard and fast rule.

[scanner_darkly]

Really in the code there is only “get” or “get/set”, and those names are just a hang over from the first versions of the code

tbh the naming never made sense to me, i just use the rule of "if it’s get or set only (“normal” using your terminology) then use _get, if it’s both use _get/_set.

but leaving the internal implementation aside, i think there is a pretty clear difference between get and set. an op that returns a value is a get. an op that sets a value is a set. some ops support both, some ops only support one or the other.

in terms of documentation i think it’s pretty clear which is which without using separate columns (and short desc can help clarify if needed), so not sure that adds useful information (as in “it’s in the set column, so it must set something”) and we don’t follow that rule anyway. so my suggestion was to claim that space and just list everything in the 1st column. so for ops that are get/set we could just list them on separate lines maybe?

G.GRP       |    get/set current group
G.GRP id    |

(bolding above added by discourse, not meant to mean anything)

[alanza]

I don’t know which is easier to implement for the web, but consider alongside the 80 characters “law”, the maximum text width a legible book (even nonfiction) is gonna have is probably on the order of 6 inches, and even smaller is often more common.

I think the Discourse formatting gets this right, for example.

[sam]

tbh the naming never made sense to me, i just use the rule of "if it’s get or set only (“normal” using your terminology) then use _get , if it’s both use _get / _set .

Yep the names were a bit daft. They came about when I merged the various types of OPs into a single super OP data structure (prior to that functions, variables, arrays and constants were treated separately). That in turn led to a big simplification of the validation and processing code. I can only imagine I was so busy thinking about the virtues of the simplification that I chose daft member names for the structs. I should have gone with normal and head (or similar).

Buy hey, naming things is hard…

Leon Bambrick (secretGeek)

And having had to spend some time dealing with cache invalidation in previous jobs, they are in fact both really hard things.

[scanner_darkly]

i think it was also a bit more confusing for me because my day job is c# so i’m super used to the c# concept of setters and getters, especially with having the sugar syntax like:

public string Property { get; set; }

[jlmitch5]

here is a link to an initial pass of changing some of the styling/ux on the teletype docs based on the mockup and further conversation with @Olivier (many thanks!!).

Feedback and testing (and any further enhancement ideas) appreciated! Feel free to post bugs here. I will update the link above as further changes are made. Current changes include:

Navigation area (table of contents)

• updated background color
• make x button part of side nav pane (and remove header)
• change “what’s new” section to updates
• expand second level of navigation when a header link is clicked
  • update selected/expanded links based on url hash on refresh/linking
• update link styling
  • underline on hover
  • dark when not focused
  • blue when focused
  • last 3 items should have smaller font
  • remove title link
  • add separators between reference materials/quickstart and advanced/last 3 items

Main content area

• left align (with padding) text. still should have max-width
• remove copy to clipboard on hover of headers (same sort of functionality by clicking navigation links)
• restyle h1-h3 headers (title, primary nav level, secondary nav level respectively)
• update paragraph text
• update monospace fonts, and inline and multi-line code block background
• migrate tables to more responsive list style
  • inline code blocks should not have background/padding
  • for ops/mods consolidate table with short descriptions and lists with long description into one
    • if there’s a long description display it, if there’s a short but no long, display short, if there’s neither display -

11/1:

• FIXED: fix scrolling stopping on iOS (thanks @scanner_darkly and @EqualTemperament)
• FIXED: fix unordered list rendering (see below for screenshot – thanks @tehn )
• FIXED: fix wrapping of ops “tables” (lists). check with android chrome – thanks @rikrak
• FIXED: fix back button not updating state/location, potentially using hashchange fn – thanks @rryy
• IMPLEMENTED: tweak css and styling to reduce prominence of sidebar based on feedback (thanks @Leverkusen and @olivier)
• IMPLEMENTED: be consistent with name used for external devices (full manufacturer company/product vs. shorthand)
• IMPLEMENTED: for mobile make menu toggle sticky.
• IMPLEMENTED: add separator between content and start of table (awaiting design @Olivier – thanks @alanza )
• IMPLEMENTED: gridify alpha ops again, with one column for code, and one column for short description (thanks @alanza, @sam @Leverkusen and @scanner_darkly)

Changes left include:

• ENHANCEMENT: update tab title and add favicon

---

• FOLLOW UP LATER: move git hash/version. would be good to show but not as heavily in the title
• FOLLOW UP LATER: add reference materials section (links to cheatsheet, etc.)
• FOLLOW UP LATER: improve ux of toggling/untoggling primary nav links (thanks @rryy)

[alanza]

すごい！Nice work! The new style really helps the readability imo.

[Olivier]

Major props to @jlmitch5 who put a ton of work into this and made collaboration really fun. Hoping we can pair up on more projects like this one if time allows!

[tehn]

looks great!

spotted a formatting issue with unordered lists i think (which are used rarely):

[sam]

Web documentation design ideas and inspiration

For pandoc, part of the problem is LaTeX, it seems like, being a cumbersome beast with a crazy “setup cost” (multi-gigabyte distros, etc). It’s probably worth asking what we want from a PDF output of the Teletype manual vs. a webpage?

Just a little note about pandoc (which is awesome IMO), it doesn’t require Latex, it’s only needed for PDFs (and in newer versions there are alternative simpler PDF backends). Really it’s a document conversion tool and in particular it has bombproof Markdown/CommonMark processing.

Latex generally has the best “font science” for print, so if you want PDFs, it’s the best choice. It’s also craaaazy powerful.

If there ends up being a consensus to drop the PDF output (I like it, but I’m also pragmatic), please please keep the workflow developer-centric, if you make it hard for the devs to keep up to date¹, we won’t.

For all it’s complexity (and all the grief those tables in the PDFs have given me), I do consider the biggest success of the Teletype docs to be their continued existence, and that is much harder achievement than is often realised.

---

¹ e.g. there is tooling in there to nag developers about OPs that are missing docs. Also the docs must live in the repo with the code (otherwise you run into chicken and egg issues)

[alanza]

Ahhh, I’m sorry, I should have been more precise. Yes! we are totally on the same page; the issue is the LaTeX bit. I love LaTeX, but it’s definitely a hefty beast.

[rryy]

Looks really good, nice and clear. One suggestion: perhaps allow the top level navigation items that have sub-menus to be collapsed/toggled? And then don’t collapse the menus when another is clicked automatically. To me, that would make it a bit easier to browse/jump around within the page. For example:

1. You are browsing the OPs & MODs, and the menu is expanded.
2. You want to quickly check on a keyboard shortcut, so you click on Keys.
3. At this point, if you want to return to where you were, it’s a bit harder to locate, as the OPs & MODs menu has collapsed.

I also noticed a minor issue: the menu state/location doesn’t update using the back button. I remember using the hashchange event to handle this years ago, but I think there’s probably a better way these days.

[Dewb]

re: the difficulty of setting up pandoc/LaTeX/etc., I have been working on a Docker-based build chain for the AVR32 modules, and because I didn’t realize what I was getting into, I also set up all the prereqs for the teletype documentation build (there were indeed some sneaky bits!)

I literally just uploaded this to dockerhub, so it hasn’t been very solidly tested yet, but if you have Docker installed and a teletype tree already clone’d and submodule-init’d you should be able to just run this command in the repo root to build teletype.hex, teletype.pdf, and the rest of teletype.zip.

docker run -v $(pwd):/target -t dewb/monome-build