Updating the teletype docs

[tehn]

i appreciate the community doc organizing as it’s related to community app/firmware development-- which is a byproduct of open-source.

but i do suspect it’d be helpful to have a centralized CHANGELOG that could indicate individual updates across all of the assorted projects here-- including the alt. firmwares etc.

this could be a good candidate for the monome-docs community repo?

[sam]

Do you have a sense for how many OPS we’re talking about? And how frequently changing? If this is a somewhat singular event maybe it’s worth it to just edit the PDF. I can probably wrangle that or I’m sure someone here can.

Off the top of my head…

• A PN version for every P op, ~12 new ops.
• Symbol mathematical operators (e.g. + as synonym for ADD, still in Polish notation though), ~12 new ops.
• Update the way II commands work, e.g. change II WW.PRESET 1 to just WW.PRESET 1 (this is really trivial to code, but it is a breaking change).
• One or two other interesting ops (like the ER op I wrote).
• I’ll also try and cross reference the source code and the docs at some point too, make sure nothing is missing.

More controversially I’m going to add some sort of inline array functionality to make things like quantisation and scale generation easier, and where you don’t really want to use a pattern to just loop through N different values. I will definitely make use of it, but I could anticipate it staying in my fork if it’s a bit much for everyone else.

Are you thinking of creating a new branch (or branches) for 2.0 and in-progress docs? It would be nice if folks could easily access docs consistent with whatever firmware version they’ve got. (There’s regular confusion like this around meadowphysics for example.)

Not too sure… maybe if I concentrate on keeping the in repo changelog up to date (I’m going to put a PR in tomorrow to update that for v1.2). Then once a release looks likely, I can use that to update the the docs repo…? Unless the docs end up in the teletype repo, trying to deal with versioning gets to be too much like real work, and I’m just doing this in my spare time (sorry!).

[ether]

Re changelog, here’s an idea:

http://feeds.feedburner.com/audiodamage

[sam]

First PR in:
https://github.com/monome/docs/pull/1

It’s just another ‘addendum’ section at the bottom. I’m having an attack ‘structured procrastination’ whenever I think about how to integrate the updates into the main docs. So I’m going to park it for now. (Unless someone else would like to have a go…?)

Instead I’m going to compare the source code to the docs and see if there are any undocumented ops (and then remove the doc strings from the teletype source code).

---

edit: all ops present and correct. Though I did spot some Orca functions with the wrong names.

I’ve also noticed that the PDF command reference is missing the V1.1 and onwards changes.

One reason why I think it would be good to either update the PDF or provide a similar HTML table is that it gives us a good overview to spot inconstant naming. I’d be up for making a small number of changes for V2 to improve usability.

[carvingcode]

Suggestion: Take a look at Audio Damage’s Sequencer 1 manual. It’s a good example. In it, all version changes are briefly (more than a typical changelog) explained in chronological order.

Then, in the main manual, the changes are simply fully incorporated in the mix.

So, for each firmware update, the changed section are rewritten or updated and its version number incremented.