#232

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; }

1 Like
#233

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)
7 Likes
Web documentation design ideas and inspiration
#234

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

4 Likes
#235

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!

6 Likes
#236

looks great!

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

56%20AM
Screen Shot 2018-10-18 at 8.34.56 AM.png878×225 40.9 KB

2 Likes
#237

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 date1, 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.

1 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)

4 Likes
#238

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.

2 Likes
#239

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.

1 Like
#240

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
2 Likes
#241

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.

1 Like
#242

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.

1 Like
#243

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 :cloud: :rainbow: the cloud :rainbow: :cloud:.

2 Likes
#244

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

#245

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

1 Like
#246

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.

Screenshot_20181019-200027_Chrome
Screenshot_20181019-200027_Chrome.jpg1440×2960 569 KB

1 Like
#247

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.

2 Likes
#248

I have worked to get my TODO list up to date based on all the fantastic feedback everyone has provided. If you don’t see something on there that should be or you find any other bugs, please let me know!

Working on defining these a bit more.

  • ENHANCEMENT: improve display of alpha ops somehow (put back in grid? move get/set to be vertically stacked in said grid? link back up to categorized ops/mods section?) (thanks @alanza, @sam @Leverkusen and @scanner_darkly)

It seems like the concensus after reading back is that it probably needs to be in a more compact table form. To help keep this terse and parseable, I like the idea of keeping things in two columns–syntax stuff in one and short description (if given) in the other. This will give more breathing room for the description and not require tons of wrapping, hyphenated words, etc. I think that “special” syntax for setting (or whatever) should ideally be called out in the short description or fairly clear from convention. We can update the documentation around any issues there. Let me know if this plan doesn’t make sense, happy to alter.

  • ENHANCEMENT: improve ux of toggling/untoggling primary nav links (thanks @rryy)

I explored keeping elements open when others are clicked in the course of development and it starts to make the experience of using the nav feel a little “buggy”. I was thinking along your line of thought you mention in your scenario–that it’s slightly “more clicks” to get back to a place or between sections. I’ve been thinking through potentially adding some sort of + icon that is to the right of the menu items so they could be opened without being clicked, though I think that might just end up being ambiguous to someone coming into the docs and just feel a bit like clutter.

Note that one benefit of keeping things more “compact” is that there is less sub-section stuff to wade through and parse “where you are”. It’s a bit nice having fewer elements available for you to parse to figure out what’s available in the docs, if that makes sense.

Still thinking on this one.

3 Likes
#249

Thanks for your efforts here! I have not read this entire thread so apologies if this is a duplication.

Whatever is used to render this out to a web page seems to have some quirks with viewing it on an iPad. It looks good, but navigation is weird. The normal “flick to scroll a lot quickly “ gesture seems to be disabled. And if you use the menu to navigate somewhere, then close the navigation menu (which seems to require two touches on the X), then it moves to a different place than where you navigated to.

This is on iOS 12 and Chrome browser. Not the end of the world but I thought I’d post the experience.

2 Likes
#250

To me the suggestions sound good, while I am not sure if I really understood, how you imagine the op-table. I had a look over the layout proposed above and it seems to me that one column for syntax and one for the short description should be fine in most cases, with get/set in the text to show that ‘set’ is possible and follows the convention.
Also two rows per op would allow one row for op syntax and one row for the alias, if there is one, and should be enough for a short description to look up.

Regarding the menu, I think it is okay to have only one element open as it is not that deep and you can reach everywhere easily. Plus it looks cleaner when all but the current element are unfolded.

Thanks for your work on this - I am sure it will end up as a beautiful and versatile tool!

:grinning::+1:

1 Like
#251

@EqualTemperament thanks for bringing that back up–I missed @scanner_darkly mentioning it when I was going through and updating my list of left things. Added!

2 Likes