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.
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)!
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)
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.
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 (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.