#1

A little background…

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.

Ideas?

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.

  1. Add a docs directory, and use Markdown and some combination of sphinx or mkdocs (and possibly readthedocs.org).

  2. 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?

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…

6 Likes
A user's guide to the wonderful world of teletype ⌨
#2

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.

1 Like
#3

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.

1 Like
#4

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.

2 Likes
#5

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.

2 Likes
#6

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.

#7

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?

1 Like
#8

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.

3 Likes
#9

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

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

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.

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

I think no.

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?

1 Like
#10

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?

1 Like
#11

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.

#12

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

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.

5 Likes
#13

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…?

1 Like
#14

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.

1 Like
#15

This is all awesome.

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

#16

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

#17

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

#18

:thumbsup:

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!

#19

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.

#20

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.

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.

1 Like