Protocols for documentation

Here we discuss approaches to documentation, with a view to developing the protocols that will go in the handbook.

The MayFirst forum has a thread of ongoing attention to documentation in their platform coop, which has similar challenges to The latest posts are this one:

and this one

Wondering if a good place to start would be to recognise that

  1. different people like different good documentation
  2. different people are able to write different kinds of good documentation
  3. no documentation is perfect for everyone; but some documentation is broadly useless

A place to start, that lies further back than that, is to contribute in a dialogue, through which the understandings, insights and commitments may be generated, which might then be rendered as self-documentation of a community’s journey of self-formation. This is where we’re at; it’s called commons.hour. It’s a time-consuming and ongoing practice! ‘A handbook’ is just a document in the middle :wink: But it needs a little planning for at this stage?

Reposting this from Reorganising & improving our forum

Here’s another post in the thread of MayFirst’s Tech Infrastructure group which is worth looking at.

In the thread they’re seeking to engage with the fact that there are “several valid ways to organize documentation for different readers coming for different reasons and from different places” - something we also need to be able to handle well, here in the forum and also in our website and Handbook.

[Edit: The response to that post is interesting too. It develops the principle of different ‘layers’ or entry routes, for enquirers with differing degrees of tech knowhow and vocabulary.]

Specification for a toolset to hold a handbook

@wouter has a strong preference to minimise the number of toolsets that we use and must maintain in our software stack, and I accept this. We agree that we need to seriously try Discourse as a toolset for Handbook documentation (flexible (over-flexible?), a workhorse, widely used and well known to sysadmins, a little klunky, not the easiest UI in the world to navigate?); Resonate is doing this Handbook - Resonate Community Forum and we need to talk to them @Hakanto . For various reasons we’re not willing to continue in the medium term with gitBook, where the Trial Handbook is being built.

MayFirst are redesigning their documentation framework - protocols, architecture, tools. Below is where they’re tending right now, regarding a toolset for handbook documentation.

What reactions d’you have to the emergent list below? I haven’t got round to a draft specification for our Handbook but this is something I must do pretty soon. Comments in this thread here will help, thanks. @dvdjaco @osb @3wc

On February 15 in (behind a membership firewall) Jaime Villarreal wrote the following spec:

We are quite fortunate that in 2022 there is no shortage of free software tools that can be used to publish a documentation web site. To make things simpler lets focus on relatively mature software projects that are enthusiastically made to support documentation projects. We can further narrow down the list by stating our essential and desired functionailty requirements.

Essential requirements:

  • Wiki like community editing
  • Markdown based markup syntax
  • Version control
  • Customizable permissions and account system to allow multiple users to manage and edit pages
  • Built-in multilingual content management
  • Allow easy publishing of different media types: images, audio, video
  • Searchable
  • Customizable navigation

Nice to have:

  • WYSIWYG editor
  • Customizable theming
  • Git based version control
  • Include multiple markdown sources in any page

Based on the above requirements I’ve narrowed down a list of 3 candidates. I found other projects that met our requirements but felt these 3 were the most noteworthy.

Wiki.js - “A modern, lightweight and powerful wiki app built on NodeJS” - GitHub
Bookstack - “BookStack is a simple, self-hosted, easy-to-use platform for organising and storing information.” GitHub
Mkdocs - “MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation.” GitHub

Of the 3 I am leaning towards Wiki.js. It appears to be the most feature complete with tooling I think will satisfy both experienced and new documentation editors. It uses markdown based and WYSIWYG editing. All documents can be exported to markdown files and commited to a git repo automatically.

This software is built on Node.js which would not have been my first preference since we don’t have any in house experience with it. This deployment would live isolated from any user data and won’t really interact with our infrastructure in any way. I think we should try it. What do you think?

thanks @mikemh - these options discussed at MayFirst are interesting. The requirements are shared I’d say. And all are free software licensed. I had been looking into Mkdocs (a fork of Readthedocs), a system that can be run in GitLab pages, but for Yust Another System to deploy, maintain and train users in, maybe the benefits wouldn’t be enough.

Now I’m looking into Wiki.js. I agree it is more interesting than Mkdocs; the wiki-like organisation, but handbook-like presentation feels nice. What you comment "This deployment would live isolated from any user data and won’t really interact with our infrastructure in any way. " would seem highly problematic to me: we want user groups on the SSO id mgt server to be replicated to the forum, nextcloud and handbook as much as we can, otherwise it could become a large burden to steward our community and keep track of who needs to be in what group and (automatically) have access to which sections / folders and so with view / edit rights. Wiki.js seems to have a decent group & page permission system.
And fortunately wiki.js does have a series of Authentication modules that can authenticate against the SSO server we’ll be setting up. To be checked is then whether the group attribute of a user can be passed on to the wiki.js system, like Discourse can do.

Back to Discourse. Indeed Resonate seems to have done an interesting job to integrate their documentation directly inside their Discourse forum. Checking the community, they seem to have used the Docs plugin; here you can see the Discourse documentation: Docs - Discourse Meta

It uses a specific view for Docs, with selected categories displayed at the top and navigation over categories and tags in the sidebar. I couldn’t find out how many sublevels can be presented in the side bar. From a UX PoV I don’t find it super easy to see where you are, a typical Discourse issue?

Having a quick read of the BookStack system, I see it implements SAML Group Sync, conveying the group attributes from the SSO database to BookStack user roles. That seems the thing. Possibly Wiki.js can handle that as well?

So yes, if possible I’d go for less systems, but that depends whether we can be comfortable enough in tweaking our Discourse forum to include a handbook space vs the perceived benefits and costs to deploy something like Wiki.js Interested to hear what others think.

1 Like

I’ve invited Jaime to this thread. Would be good to understand the SSO aspect of wiki.js? @jamie @freescholar

@3wc - wiki.js is part of the architecture of federated wiki I think. D’you know about wiki.js from that standpoint? For example, does this relate at all, to the implementation of Keycloak in federated wiki, as you have so heroically done :pray:

I’m not at all impressed by that implementation of a handbook in Discourse. The nav sidebar has no nesting of categories (compared with Resonate’s handbook for example, which does) - just a very flat file structure. And they use a million tags. Seems like it just growed, with little or no design attention :roll_eyes:

Tagging, graphing and handbook structure

This wiki.js site Folder Structure & Tags | Wiki.js has a VERY flat and therefore opaque file structure: no nesting in the sidebar, and pages are internally complex containing a number of anchors/subtopics. Like the meta.discourse forum, seems to rely primarily on tags.

Tags are powerful. Also, ‘democratic’ - they can be endlessly invented (resulting perhaps in a complex and arbitrary lexicon, as in the meta.discourse forum - the moderation/curation issue). But some transparent overall nested (or more fully relational, perhaps ‘woven’) structure in a handbook seems essential. Comments on this as a design principle?

Hierarchical/nested sidebar is one way to display structure: familiar and very clear. What other ways are there? Seems I’m talking about mapping of a quite complex (multidimensional, relational) system of resources.

Graphs? Clickable graphs are cool (the federated wiki community are very good at this, as a feature within wiki) and also powerful - but every graph is ‘new’ to the reader and needs decoding to be useful. So graphs ought to be well designed and reviewed, not ‘just growed’ or ‘organically emergent’?

If tags are a primary means, at the very least there needs to be a way of displaying a tag cloud. Tag clouds basically follow traffic, rather than logic. How useful is that, in a handbook (as distinct from a list of FAQs, for example)?

Is it just me that has a hangup about (‘woven’, visible, mapped) structure :roll_eyes: The Trial handbook we’ve been hacking Welcome - handbook trial is a quite rich body of documentation, covering not only platform features and operational protocols but also design principles, project aims, coop-commons governance, community formación and federation/collaboration practice. Thus, a relatively complex system of categories aka mapped topics, rather than a simple FAQ list. For sure, it should contain such a thing, easily findable?

Hey y’all, I’ll chime in re: Resonate Handbook and answer some questions that were PMed to me.

I don’t have any devotion per se to using Discourse as a Handbook, but it has proven quite useful to us.

Why I chose Discourse for Resonate’s Handbook


We urgently needed “one source of truth” for key info at Resonate. Using the forum for this was “safe enough to try”, so I went with it rather than waiting any longer.


If we wanted to move to another format in the future, it seemed easy to copy/paste materials.


search unifies forum and handbook

For each forum category, you can go to its settings and adjust its priority in search. The hope here is that folks arrive at our forum and search for information, search results will prioritize Handbook (very high) and Help Desk (high). If Handbook were outside Discourse, this search wouldn’t be unified and we’d have to direct folks elsewhere. Since I’m aiming to use the forum as our main “customer service” area, and have it be a place where members can find info independently, this is great.

commenting under handbook topics

Because the Handbook is part of the forum, folks can ask questions and reply on those topics directly. I use these comments to refine Handbook topics and then reply that the topic has been updated – easily notifying the main audience for the changes. This has fostered a good habit where users navigate to these topics, see that others ask for clarification there, and follow suit.

minimize labor

When I reply to common questions on email or social media, I send them to the corresponding Handbook topic. This also serves as a natural way to invite folks to our forum where they can explore and take initiative.

Similar to the point above, if the Handbook is inside the forum, then folks are less likely to choose private/direct means of contact for support – email, etc – that raise the labor burden on staff. The amount of email we’ve received has dramatically decreased since switching to this Handbook + Help Desk + Forum setup.

Replies to PM questions

themes and fonts

I’m… not too familiar with these settings on Discourse yet.

Taking a look around – we’re using Arial as our base font and heading font. Under Admin > Settings > base font; heading font.

We have a unique theme called Resonate, but I don’t know the history of it. It seems Angus updated or adjusted it while he was with contracting us. Here’s the current settings:



If Handbook were a parent category, I believe you’d be able to do two levels of nesting. I currently have it as a child category of Help Desk so that folks who go to Help Desk bump into Handbook topics among other discussions. This may not be ideal in the long run.


The sidebar we use is made by Pavilion. It’s called 🗃 Category List Widget - Layouts - Pavilion. Since we use our forum as a workspace, this is very helpful. Highly recommended

Problems and considerations


Recently, the DiscoTOC component which created a really nice within-topic header navigation has stopped working with the Docs plugin, which is a bummer. It’s still working for the standard view; compare below:

Standard + DiscoTOC: Submitting music - Guides - Resonate Community Forum
Docs - DiscoTOC: Submitting music - Docs - Resonate Community Forum

Who edits the Handbook?

Because of how Discourse is structured, you’ll need to decide who or at what point someone has the right to edit these materials. Compared to the liberty of a true Wiki, a Discourse Handbook will likely be less inclusive and experimental.

Complimentary tag component

Recently discovered this tag component and love it. Its usefulness can be seen on a category such as Proposals to light-weight label proposals as they change status.

I likely missed some of the questions – ask away and I’ll help out when I can!


Packed with goodness, thank you @Hakanto for settling down with this. We’re basically on the same page (!) methdwise and socialwise, regaring the central role of the Forum for example. Will browse and digest.

1 Like

Another discovery:

modularity of discourse topics

I invited one of our dev volunteers to write a guide for new dev volunteers to build in our ecosystem – and to write it as a new Topic. When this topic was done, adding it to our Handbook was as simple as changing the category.

Since then, we’ve created a new category called Needs which highlights key ways to help, volunteer, contribute, etc at Resonate. It has been extremely helpful, not only for coordination but for our internal sense of what our needs are.

I concluded the guide which had been recently written made more sense as a call-to-action. Launching the call-to-action was as simple as changing the category to Needs.

Lately I’ve been treating changing categories as a sort of kanban system – moving Topics through the forum as they move through the narrative of collaboration our parent categories imply. The modularity of Discourse Topics makes this possible.


Sorry I’m just now catching up this thread. Really appreciate the references to the research and ideas we’re sharing about documentation for May First. I’ve added a few more things to our list and will probably continue to do so. There are a fascinating amount of recommendations and strategies for documentation out there. :star_struck:

As far as tools go… the examples in this thread demonstrating how Discourse itself can be shaped into a repository for documentation are very impressive. Yes I’ve invited our documentation team volunteers to experiment with Wikijs for now but we haven’t to committed to anything yet. Honestly as long as we can keep anything we write in a markdown format that can be easily migrated it feels safe to try different things (even Discourse).

I haven’t really explored how we’ll integrate SSO and authentication options for Wikijs with our existing system and you might have noticed that wasn’t in our list of requirements. I’m more interested in testing how easy it is to edit multilingual content and organize navigation right now. I haven’t tried ALL the plugins yet :face_with_peeking_eye:but I find Discourse really lacking in its facility for managing multilingual content as is. If I can get those things out of the box from a tool made for documentation I am willing to to fight with SSO later if necessary.

Why do I feel that way? Logins to our current wiki based on Trac have been integrated into our centralized authentication system for years and that has not resulted in the masses clamoring to contribute and improve documentation. I don’t think this should be the deciding factor for us at May First. Organizing wider participation is more of a social and political challenge than a technical one. I am more interested is making it super easy for a small team who are interested in working on documentation to edit and rearrange things as needed.

Every community is different so any approach that is working for you is a good one in my book. :+1:

1 Like

Really helpful and timely to have this commentary @Jaime thanks. Yes, I think I’m with you on which is the cart and which is the horse.

Hiistorically, coming from libre software culture, SSO has seemed like a holy grail. But as we expand our frame, Language equity begins to be prominent in our principles too - as you say: “Organizing wider participation is more of a social and political challenge”. I’d expect to see some re-orientation of perspective here. So your reflections on Discourse weakness in this area are welcome.

Nevertheless, in the short term, we do need to do some Discourse hacking, just to determine how far the old workhorse can go, as a container for a Handbook. We definitely want to get out of gitBook, and w’d rather not start hosting another suite of tools if we can avoid it just now. Watch this space. We’re certainly watching yours! Abrazos

@3wc D’you have a take on this? Strengths and weaknesses of Discourse?

The subcategory Handbook (now Handbook old) is superseded 12jul2022 by a new main category: Handbook

However this thread remains open for discussing general issues of documentation practice.