Teletype docs enhancements (redesign in progress)


#201

great, thanks! will take a look!


#202

i’ve merged the PR (with a small change in wording), thanks again for your help!


#203

do we have a way to generate key reference in the same way we generate command reference? for key reference we have a really outdated static PDF which should be replaced/removed.


Teletype 3.0
#204

There is already a key reference in the Teletype.pdf, so yes. It may be possible to generate a separate PDF from data we already have in the vein of the Cheatsheet… I’m happy to look into it if you don’t mind it being low priority for me.


#205

… is this the point where I open an issue? I’m not sure what the ettiquette is for discussion here vs Github


#206

good idea to track it as an issue - could you add it? and tag it with needs documentation.

low priority is fine, we have the manual which details all the shortcuts, having a separate cheatsheet is nice but not a must have. removing the outdated doc is more important as it’s still a source of confusion for new users.


#207

… I probably should have asked if /monome/teletype was the right place to open the issue. I don’t think I have the permissions to tag it as needs documentation if it’s there.


#208

yeah, you can only open issues in the main repository.

thank you - i added the tag and assigned it to you, this way if somebody has the time to work on it they can coordinate with you.


#209

So, no movement on this on my end, but I’m loving @jlmitch5’s work restyling the HTML manual! Some things I’m thinking could make a nice partner to his work on the redesign include:

Refactoring the layout—especially on the web it doesn’t make sense to have almost every Op / Mod be documented in two places within the manual (the sections for the various groups of Ops as well as the master list of Ops in alphabetical order)

  • actionable suggestion: replace the Op / Mod documentation in one of these locations with links to the other. At first I thought maybe for readability purposes the alphabetical list could be the master one, but since it is a reference and not a novel, having the index be terse (hence more searchable) seems like a better idea.
  • include a separator, like even just a horizontal rule, between the talky bit introducing the group of Ops or calling out anything of special attention—and the list of Ops itself.

The whole thing could use a careful proofread and thoughtful style edit.

These are things I definitely do not have the time to work on in any organized fashion until … December at the earliest, but if they still need doing, I’ll probably do them eventually.


#210

@alanza I can’t seem to find the HTML version you speak of and only find the pdf, can you give a pointer?


#211

I’m not sure where the official one lives currently, but I meant this “beta” HTML manual on another thread that @jlmitch5 and @Olivier have been working on.


#212

Migrating the alphabetical Ops list to links that reference the op section makes a lot of sense. I’ll add that to my todos.

Separator makes sense too, @Olivier let me know if you have ideas on weight/color (as well as the other separators in the ops section currently in the beta)

I started the other thread more for inspiration and ideas, might be a good idea to merge the more teletype docs specific back over here. Thanks for linking to it!


#213

@alanza thank you for linking the other thread, somehow i completely missed it! and huge thanks to everybody involved for the initiative and the work. i’ll post feedback here - let me know i should use the other thread instead!


changing “what’s new” to “updates” - updates for me is more generic so hides the purpose somewhat. also “what’s new” seems more inviting maybe?

navigation on ipad - is there a way to keep the current location in navigation pane after i collapse it? if it’s down the list i have to scroll after i open it again.

should have more visible separation between different sections, take a look at how alphabetical list follows the advanced section.

not sure this is something that can be changed - for some reason scrolling on ipad stops as soon as i stop touching it which makes it difficult to scroll fast.

- in op descriptions could probably be removed?

might change my mind when i see it in practice but my concern would be introducing an extra click for the alphabetical list, if i understand correctly. i think the use case for the alphabetical list is to quickly check a syntax for a specific op, so maybe we should at least include the op syntax with parameters listed and make it a link to the full description? or even adding a short description if the op has one (in addition to linking to the main description).

fwiw i don’t use pdf either but i think the command reference should still be a pdf as it’s more likely to be printed.


#214

Ahhhh, you’re actually asking for what’s already in place. Upon revisiting it, I think that my concern is actually rather that the behavior as in the screenshot below is broken—this looks like it ought to be a table, but instead it’s somehow become just a list, which makes it tougher to scroll through and tougher to read.


#215

yeah, agreed the alphabetical list should be more terse. maybe just a list of ops with parameters linked to their actual description? like this:

& x y
? x y z


#216

Thanks for the feedback @alanza and @scanner_darkly! I’ll let @jlmitch5 weigh in on the actual technical feasibility of these ideas, but from a design perspective…

That sounds fine by me. I wonder, though – do we need to have older TT versions in here? Perhaps we could reserve this section for the newest release (in this case 3.0) and move everything else from previous releases down to the Changelog section?

That’s definitely a remaining action item on our list!

Noted, and will make sure we tweak this.

Re. tables

Agreed. In fact, the styling of the tables in the beta was initially meant to improve the readability in mobile contexts specifically. @jlmitch5 – I wonder if we can preserve the original table layout (but with updated styles) for desktop. @alanza, if you feel like this is not especially readable even in mobile environments, then I think we should definitely think of alternatives!


#217

ahhhh, on my phone, it’s beautiful! It just becomes harder to read on the desktop. (although, remembering the meaning of the formatting is tough on mobile.)


#218

:+1: thanks for all the feedback @scanner_darkly (and additional feedback @alanza). all makes sense to me and agreed with @Olivier

Thanks for explaining how y’all use the alpha ops/mods table/list. It’s not something I’ve ever felt drawn to when using teletype, so it was hard to think about what the ux should be. Agreed that making it tables makes sense.

EDIT: after reading @scanner_darkly’s idea of aligning op/set/alias in rows I feel like is a better way to reflow this than what I had.


#219

yeah, this makes sense (and would match the naming better).

speaking of op tables, should we list OP (set) and aliases as separate columns? not every op has a set version and only a few have aliases, so that’s a lot of wasted space:

maybe they could be listed underneath instead? this would also remove the need to have vertical separators so then we could just use a horizontal separator for cleaner look (i guess we’d still need a vertical line between OP and Description)


#220

if the short description consistently uses “get/set”, maybe we could save ourselves the trouble and just omit them all? at the cost of explaining the syntax in words elsewhere, but I feel like that will be more useful for (a) indoctrinating new users into the syntax and its peculiarities and (b) eliminating noise for experienced users.

Similarly, maybe aliases actually could just be separated by a comma, spacing or a short line-break.