Copy pass for 1.6.0 docs #1.

[infovore]

So: a few changes I've made, which are up for discussion:

• house style seems to be passive voice, so I've removed 'you' where
  appropriate
• house style also calls keys on the grid 'keys' or, wherever possible,
  just refers to them by the function they are performing ("press
  'octave'; the octave key will light"). So I've removed 'button' and made
  appropriate changes
• for entirely personal reasons I found 'extended parameters' more
  appropriate than 'parameter extensions'
• I've moved some things around. More specifically: the "parameter
  extensions" documentation mentions loop/probability/division before
  we've explained it in the main documentation! So: key, 'basic'
  parameters are explained; we mention that there are also extended
  parameters, see later; then modifiers are explained; then the extended
  parameters section
• replaced h5s with h4s, h5 renders tiny in the default stylesheet
• sub-page, not sub page
• Took a pass at explaining each mode in a single sentence. Also removed
  some of the narrative style (referencing previous paras) because
  a use-case for documentation is jumping straight to a para. So there's
  a bit more repetition, but I think that's OK for technical writing.
• added TODOs for the Teletype commands

[infovore]

this is NOT FOR MERGE because we still need to do teletype.

[mtallen]

Man the default diff functionality for git is poor :/

I like all of your changes. Thank you for the through pass! They make it more readable. I still think the meta-patterns section is a big block of text and I would like to further iterate on that at some point.

I looked for a best practices document when I started but really just had to infer a bunch of stuff. I felt the "you" and "your" in my pass felt clunky, but I was more than happy just trying to jam something out. I don't do much public facing docs (mostly internal stuff) so I am used to using my personal voice when writing. (Im amazed I didn't drop a couple of F bombs in the ansible document)

The other thing that I noticed when first starting with my grid a couple of weeks ago was that this single page, with the intro stuff and the arc stuff and the grid stuff, is super unruly, and will only get more cumbersome as features are added. It takes me a while to mouse scroll down to the specific area I want. I could definitely see doing a table of contents/ document navigation, or even splitting stuff up into sub pages. Also as you point out formalizing a style guide would be super helpful for future document users.

I was also thinking about porting the master image files over to the svg format, or a layered image document. I am lucky in that I extensively use the adobe suite so opening/ editing the files was easy, however I am not sure how closely inkscape or other open source apps keep up with the adobe file formats. So making them something more "open" should be a point of discussion.

We should also include the font (DINOT family) so people can install that, or barring license issues, change it to something open/ more universal.

Other than all that I heartily give your changes and directional suggestions a big fucking thumbs up!

[infovore]

Yeah, there are no best-practices documents, which is fairly common, but hard for new documentation writers. On the flipside: easily worked on with a community, and whilst my C isn't up to the firmware, my writing is up to this.

The big page is unruly, and maybe even some jumplinks would help. I'd also note that the Grid docs for ansible are always in a bit more need of work than the Arc ones - they mainly reference previous revisions of the same applications, whereas Arc is all-new and understandably had the majority of focus. (writing the Earthsea docs for Ansible taught me this).

Font: this is tricky, we definitely can't include that in an open source library. But good thinking - the AI documents are appreciated, even if they are proprietary. I made all the graphics for the Earthsea docs by shifting pixels around the page... so we probably need to work out what to do here as a team with some @tehn input.

Anyhow, glad you approve and it's not too problematic. I've looked at the code and written my best description of the TT functions... but I need to page freqout regarding some of the functionality!

[tehn]

looking fantastic! extreme gratitude.

[infovore]

Cool. I'm happy with this to merge/deploy, though it might be worth checking it with @AaronMeyers to confirm it really is all intended behaviour.

[AaronMeyers]

Thanks, this adds a lot of clarity!

[tehn]

ready to merge?

[AaronMeyers]

Just one thing for the Teletype Clocking section...

"To do so, hold down the scale key; the four leftmost keys in the top row will enable or disable Teletype clocking for the relevant channel."

Seems weird to say "hold down the scale key". It only needs to be pushed in order to go to the scale screen.

Also, perhaps it should be mentioned explicitly that when a track has teletype clocking enabled, it no longer responds the the master clock?

[infovore]

Thanks @AaronMeyers, both good points. Pushed a change with those in. @tehn, fine to merge with me.