#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
#21

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?

3 Likes
#22

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.

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

1 Like
#23

Re changelog, here’s an idea:

http://feeds.feedburner.com/audiodamage

#24

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.

2 Likes
#25

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.