Updating the teletype docs

[sam]

How about using asciidoctor for the docs? Really easy to edit as it’s similar to markdown, and it generates really nice HTML and PDF.

I always a bit sad that something a bit more proper like Asciidoc didn’t take off, Markdown is great and all that, but it can be too basic. Did you see that Ableton were using it for their Push documentation? The GitHub render is good too, which is a big plus.

Do you know of any code to convert the HTML to a website like Read the Docs do? (example, and source - uses mkdocs)

The big advantage of Markdown is that people know how to use it already (and if they don’t it’s a useful thing to learn, AsciiDoc is cool, but a more niche), so if a lot of non-coders wanted to contribute then I’d go Markdown.

---

@scanner_darkly auto-generating would be awesome, but as far as I know most tools are like Doxygen, API docs for programmers, unless you know of another? At the moment I’m only talking about end user documentation. In fact I’d probably start by importing the current docs and studies.

Do you mean GitHub wikis? I’ve yet to see a really good one unfortunately, and the navigation is painful. Wikis are much easier to edit, but I do think the GitHub process for editing repo files works really well. I’ve used it myself to do the drive-by-PR to fix typos that I find in other peoples code. Plus I like that pull requests give us the opportunity to acknowledge and thank people for their contributions.

---

One big plus point for both AsciiDoc and Sphinx (& Markdown or RST) is that they’re both capable of generating HTML, PDF and ePub.

[scanner_darkly]

yeah, good point about converting to other formats which wouldn’t be easily done with github wiki (which is indeed what i meant). and yeah, agreed on github wiki in general, i just like having it close to the actual code / releases and a built in editor. this actually gives me some things to consider in regards to orca manual which i’m in the process of editing, it’d be nice to provide a pdf as well. asciidoc looks great, i’m going to check it out.

re: autogenerate - i’ll investigate if there is anything not API specific (we use swagger at work but it’s RESTful API specifically). this could be used in addition to the main manual.

[tehn]

right now the docs run on a digitalocean server with the main monome.org site, which is basically a private git and jekyll.

if there’s some sort of submodule wrangling to get the markdown file and image folder to this site, that seems ideal.

another option is open-sourcing the whole monome/docs area as a whole. again i’d need to figure out how to submodule this into the server.

likewise, we can host docs on github and i can just have http://monome.org/docs point to github.

[sam]

Does the teletype documentation need to be treated differently to the other modules and documentation? Is it that much more complicated? Would a PDF or an ePub be beneficial?

If the answer is ‘no’, then maybe open sourcing the docs would be the simplest option, if you don’t want to fiddle with submodules, you could host it as ‘docs.monome.org’.

The big downside, is that the docs will not stored in the same repo as the code, which causes a few hiccups with work in progress features. E.g. while working on the V2 features, at what point do the docs get updated?

[carvingcode]

Couple thoughts: For the user of docs, the format is not as important as how complete and current they are. For the maintainer, it’s more important that the method be as simple as possible.

Open source docs can quickly become incomplete or sloppy as people move in and out of the project.

[ppqq]

I think it would nice to do this in such a way that it didn’t require @tehn’s time, but instead it could be edited by the community.

Emphatic . This is the motivation behind the community docs repo as well:

monome-community/monome-docs

(But it’s little more than a promise as of yet.)

Any streamlined process we can share between module docs and community-supported docs like FAQs, tutorials, etc. would needless to say be awesome.

Thoughts anyone, good idea or bad?

Besides general enthusiasm, I’d throw my vote for markdown. And volunteer to help write some docs besides.

Moreover, if there’s any momentum we can create around community-driven documentation I’m all for pitching in. Happy to share technical burden as well.

auto-generating would be awesome

Used judiciously, I think this is a great idea. For example, generating a page capturing OPS would be a snap and very handy.

Does the teletype documentation need to be treated differently to the other modules and documentation? Is it that much more complicated? Would a PDF or an ePub be beneficial?

I think no.

The big downside, is that the docs will not stored in the same repo as the code,

This would be a drag I think and ideally avoided.

Any reason the monome module docs couldn’t just redirect to the latest in the teletype repo?

[sam]

Okay, let’s make life a bit simpler and say we’re going to stick with Markdown (or rather CommonMark). Everyone knows it already, and we have several options for publishing systems:

• static site generation via Jekyll or better yet, Hugo.
• automagical website, PDF and ePub documentation generation via Sphinx.
• easy automagical website documentation generation via MkDocs.

All of them can use Markdown, and in all honesty it’s probably not that hard to switch between them. I expect the actual Markdown files will need very little changing.

I’m also strongly in favour of keeping the docs in the teletype repo, that way they can be be updated alongside new features.

So, @tehn, I know you’re super busy with Arc and Ansible stuff… but if myself and @ppqq (and others?) were to create a /docs dir on my fork, would you be able to send us a copy of the various teletype Markdown files from your Jekyll installation to get us bootstrapped?

[tehn]

yes i’ve been working on this just now!

i plan to use jekyll as-is on the site, with a script to update the main site with the docs repo (which will be hosted on github)

will be ready in promptly.

[tehn]

ok-- the entire tree for monome.org/docs is now in a pubic git repo:

monome/docs

changes to the repo will not be immediately reflected on the monome site, but i’ll be alerted of changes and will push updates.

regarding contributions-- i’m not sure how people will prefer editing. you could certainly install and run jekyll, or use a markdown editor like macdown. let me know how/if i can facilitate further.

[sam]

Brilliant.

I think for now I’ll stick with updating the the docs repo rather than trying to move anything to the teletype repo.

[quote=“tehn, post:12, topic:4775”]regarding contributions-- i’m not sure how people will prefer editing. you could certainly install and run jekyll, or use a markdown editor like macdown. let me know how/if i can facilitate further.
[/quote]

The easiest editor to use for most people is probably the built in GitHub one, the Markdown rendering is really good (and rendered diffs too), and it streamlines the PR process. Which is especially good for non-technical people. Just hit the edit button to get started.

(FYI I always open PRs usually, I prefer that to pushing directly to master)

---

I’ll try to get a PR in to add the updates for v1.2 to the docs, as well as fold the updates into the main text.

After that, I need to have a bit of a think… rambling thoughts follow…

As I said at the top, I’d like to add a bunch on new ops, but it needs to be easy for people to find out about them. At the moment the main docs serve as both an introduction and a reference. Now that I know how to use the teletype, I find that the introduction gets in the way, all I want is the reference. Maybe splitting into 2 is the way to go. There is also the PDF, but I can’t update that. So maybe have the command reference as a Markdown file on the website, but also a way to convert it into a PDF for printing is the way to go…?

[ether]

perhaps another dedicate topic or tag or whatever you call it in Discourse for tracking important updates? To both docs and apps/firmware. I find when I come back here (and other similar places) It’s not immediately obvious what’s the latest version of things, where to download, which threads to check, etc.

[ppqq]

This is all awesome.

Maybe splitting into 2 is the way to go. There is also the PDF, but I can’t update that. So maybe have the command reference as a Markdown file on the website, but also a way to convert it into a PDF for printing is the way to go…?

I really like the flow of the current intro docs and I think we’d lose people if we broke things up too much. That said, the reference is invaluable and we should find a way for you to update it. My first blush was that it should be generated from MD but then I took another look and realize that like so many things here, the reference is itself a product. It’s really quite nicely laid out. If we went to autogeneration we’d lose that.

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.

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

[ppqq]

I find when I come back here (and other similar places) It’s not immediately obvious what’s the latest version of things, where to download, which threads to check, etc.

Yes! I think this is very confusing. And even more confusing with different versions of the firmware and docs that may be ahead or behind what you have locally installed.

For a roll-up of things like this maybe we could create a modules section in a community-managed FAQ on the nascent community docs repo? (Feel free to chime in on the corresponding issue if you think it’s a good idea!)

[carvingcode]

Shouldn’t updates and related docs be located on its product page? Discussion about those then occurring in the forum topics?

[ppqq]

Shouldn’t updates and related docs be located on its product page? Discussion about those then occurring in the forum topics?

Ideally yes.

The trouble is it’s hard to find the relevant topics and it’s especially hard with modules that have multiple firmwares (and revisions). I guess I was proposing a kind of curated aggregator. An entry could very well just enumerate threads to pop over to.

Not at all wedded to the idea though!

[carvingcode]

I’m not following the problem… There’s docs and updates - those should be handled by the product owner/team. Then there’s discussion. Online forums have never been an ‘all thing alike in one place’ extremely organized medium. Lines seems pretty good.

[ppqq]

I’m not following the problem…

For regular forum members there isn’t. Search for all the threads that express confusion over meadowphyics firmware or Kria clock support and you might see where I’m coming from though.

There’s docs and updates - those should be handled by the product owner/team.

I think the point is that to at least some extent that’s us. A community-driven FAQ is just one stab at a way other folks can help carry the weight.

[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