#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.

1 Like
#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.

1 Like
#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.

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

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

3 Likes
#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.

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

05
Screen Shot 2018-10-18 at 16.56.05.png1518×872 24.2 KB

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

1 Like
#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!

2 Likes
#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.)

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

1 Like
#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:

image
image.png811×284 6.01 KB

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)

1 Like
#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.

1 Like
#221

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…

1 Like
#222

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.

  1. 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:

31
Bildschirmfoto 2018-10-19 um 11.15.31.jpg1814×1168 258 KB

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

  2. 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?

  3. 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.

2 Likes
#223

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

#224

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

1 Like
#225

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?

tt-docs-adjusted
tt-docs-adjusted.jpg1528×805 242 KB

4 Likes