Teletype docs enhancements (redesign in progress)

[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 

[Dewb]

If anyone is tempted to try that, you might want to wait a bit, the image is 2.43GB! Let me see if I can clean up the cross-compiler build folder after it’s built.

[alanza]

I think one of the main concerns with LaTeX is that the standard distros are multi-gigabyte downloads, which probably seems increasingly burdensome the less likely you are to use them outside generating documentation and the slower your internet is.

[Dewb]

That’s a good point. Ideally we can get to a place where nobody has to do any manual installation or building and it can all happen automatically in the cloud .

[jlmitch5]

very nice! since you’ve already dockerized it (and the repo is public), it’d probably be pretty easy to configure CI to pulldown that container on the branch. ZEIT now could do it I think (and I’m sure others). Unsure about the output-the-build-artifacts part of things

[scanner_darkly]

weird that the posts that got moved to this thread are not arranged chronologically, never noticed that before…

[rikrak]

Some text in the Ops/Mods section appears to be rendering incorrectly on my phone (Samsung S9+ running Chrome) . The right-hand side is running under the padding(?). I have attached a screenshot.

Although I predominantly use a printed copy of the pdf manual, I do refer to the web version on my phone from time to time. I love this new, clean design and will certainly use it more often.

[sam]

I think one of the main concerns with LaTeX is that the standard distros are multi-gigabyte downloads, which probably seems increasingly burdensome the less likely you are to use them outside generating documentation and the slower your internet is.

I don’t believe @tehn has been able to download Latex precisely because of this.

On the flip side, at least one of the contributors to the first version of the docs did it by only building the HTML output.