#198

I submitted a PR (my first ever :see_no_evil:) against the grid2 branch with a little section added under Quickstart!

5 Likes
#199

I’ve been using a 64Gb USB 3.0. A bit overkill maybe? :slight_smile: But it works.

#200

Well, good to know! My current guess is that because I had previously formatted the non-working disk as MacOS-whatsit, the permissions are all screwy and above Teletype’s pay grade. The other drives I tried were 4 and 1 GB, respectively, hence the previous hypothesis.

1 Like
#201

great, thanks! will take a look!

#202

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

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

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

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