I’ve got quite a bit of free time between now and Christmas, so I’d like to squeeze another round of teletype hacking in. Ultimately I’m looking to add some (sympathetic) new ops in, such as PN versions for every P op, and also some private ops for my own compositions.
In order to get that done there are two things I need to sort out. One of them is fiddle around with the source code to make the parser much more efficient (at the moment every extra op makes the parser a little bit slower). I’d like to do that later in the year, once all the wonderful new Ansible and Expander additions have had a chance to settle.
I’d also like to update the documentation, especially as there is some new functionality, and I want to add more, and we’ve also got the V2 stuff on the horizon. It’s going to be important to make sure that all of it is easily discoverable. 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.
At the moment I’m thinking the best way to go would be to integrate the documentation into the teletype repo, with the implication that the documentation is updated at the same time as any new functionality is added.
So far I’ve got 2 difference ideas for how to do this.
Add a docs directory, and use Markdown and some combination of sphinx or mkdocs (and possibly readthedocs.org).
Add the documentation directly to the source code and write a custom utility to extract it.
Personally I favour approach 1 as:
any custom code to generate the docs will be hard to maintain.
only coders will be able to edit it, which would be a shame as it’s super easy to edit docs on GitHub (even if you can’t use git).
Thoughts anyone, good idea or bad? I’m more than happy to the technical side sorted out (e.g. auto-publishing to a website, weaving some Latex magic to make pretty PDFs), but it would be nice to have as much help as possible with the actual documentation.
Finally, Hacktoberfest be upon us, if I can get something set up relatively soon, this could be a nice way to encourage contributions (especially from non-coders) and get some T-shirts…
might be misinterpreting your intent but feels like 2 separate things here - community based doc editing and autogenerating docs for new ops? both are good ideas i think.
what about just using git wiki to host/edit the main manual? not sure about the pros/cons compared to having docs folder in the repo itself, with wiki i guess you don’t need to worry about hosting it elsewhere and you have a built in editor for markdown etc.
for new ops i imagine there should be a number of tools to autogenerate docs on merging pull requests or something like that, and i like that it’ll force documenting ops in the code - makes it easier for development too.
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.
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.
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?
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?
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.
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…?
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.
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.)
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!)
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.
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.