a bit of my experience of documentation on axoloti, which is a kind of similar product to norns.
(at least in ‘challenges’), and also uses discourse (and GitHub, for both code and contributions)… its been running for 3 years now(?) so is mature, and i think has a pretty vibrant community…
so when we first created the axoloti discourse forum, I seeded the forum with a user guide, and install instructions all created in category (called user guide), using wiki posts.
it took me a while, and im not a technical writer, just a developer, so the hope was others would expand an improve on it.
some thoughts on this:
discourse only allows the first post to be a wiki entry.
this actually is quite nice, you can actually allow comments to be about improving the doc, or close it, but this still allows editing.
the markup is ‘ok’
i thought fine for my needs, but many kept saying it would be better in a proper wiki (linking is the main thing, but i also often users lack of familiarity with the finer points markdown)
its advantage is quick and easy (for me), and it sits nicely alongside other posts for searching, and its easy to link to… but its has it limitations.
(as @vehka has just posted, we also export it to html (or pdf?) so it can be delivered with the software as offline documentation)
a technical issue, is there is no multi user locking/collaboration (at least last time i tried)
this means two users can edit, without any notification, and the the last ‘save’ wins.
really was only an issue initially, when i was adding new parts, and someone else decided to fix my typos
flagging content for adding
thats an interesting idea…
id say that one issue is lines (for norns) is kind of promoting a use model of discourse that its not designed for… discourse (and most forum) are designed such that new topics are put in new threads… and so tagging etc, is done at the topic level. and then are grouped by categories
whereas lines tried to put all norns topics into one topic (ok, several topics like scripting, but still coarse granularity)
so its creating a rod for its own back really
move to a development category with individual topics, then you can start using existing discourse features (as others monome products have?)
this also empower users to be more selective over the topics they wish to watch and not.
community documentation experience
I have to say im intrigued by any model that encourages community members to help the documentation effort.
that said, i suspect the ‘tech’ is unlikely to be the issue
this has been an area I’ve been hugely frustrated with on Axoloti…
whilst we had core documentation in place, of course new users wanted more, understandably. and they also were frustrated that this meant searching over the forum.
we agreed this was a problem, and ive been very vocal that the community needs to be part of the solution.
but countless times, Ive had new users turning up whinging, and saying if I help them get going, that they will document their process, and then contribute it… so i carried thru on this, gave them even more support than normal, and even said i would review what they put together.
sounds like a fair deal, good for everyone - no?
not one of them actually followed thru, sure they took the support and guidance, but didnt write a thing.
the results is , we have had only a couple of contributions to the documentation effort (which ive of course been hugely grateful for!)
but still we get the same complaints.
so unfortunately it appears, everyone wants documentation , but few are willing to put the effort in to create it.
so yeah, I feel a bit jaded/cynical about it now
important note: to balance this a bit…
i think the reason im frustrated about this, is because the rest of the ‘community’ features of axoloti works really well, we have lots of code/patch contributions, and lots of users that help each other on every aspect, and there are excellent discussions on broader topics like dsp.
so… its just this one aspect, that feels like it lets us down, and its the first encounter new users have.
so, if a different model , as @barnaby suggests works, it be awesome, and id look into following on axoloti…
from axoloti, id also say its apparent some people just dont read documentation, they will still want to post issues/discuss…
but at least if you have the documentation, you can just link them to it
(also as common issues arise, i try to update the relevant ‘doc’, again being in the same place as posts, makes this easier.)
however, i think alternative forms work really well…
the studies are a great way.
axoloti has tutorials, and help pages (like max), but they lack the explanations of the studies, and i think the studies are really nicely balanced in terms of size/length.
ive also done quite a lot of videos , which is now my preferred route
seems a split on users who prefer videos to docs, and vice versa.
(more on organelle, that axoloti in fairness, just because thats where my focus has been)
but also you have to consider the real issue…
e.g. do most users want a rPI how to guide, or would they prefer a download image.
(i did the former, as i didnt want to tread on norns toes, but i suspect most wanted the later!)
if anyone is interested in what this all looks like you can see it here:
also you might want to look at how axoloti discourse is structured…
of course, its different, as its doesn’t have the mixed focus of lines, but it does have the ‘development of code’ vs end-user split of norns.
one particular area that might be interesting, is how we organised ‘contributions’, basically giving each contributor there own thread - this seems to work quite nicely,
it gives each contributor a place to talk to ‘their’ users, and announce updates…
perhaps not the best way to organise it, but it has a nice feel to it