Tools for a handbook

Organization circle Handbook & forum design
1

Here we assemble information and assess documentation tools that are suited for a handbook.

2

@wouter wrote (in matrix):

Resonate forum . . has a nice Handbook inside. We might want to study this: Docs - Resonate Community Forum
It is a Discourse forum with the Handbook a particular subcategory of the Helpdesk category. And they have worked on nice iconography and tweaked the way categories are presented.

If we would do sth similar, the advantage would be to have one less platform environment to maintain and our users to learn and keep track of.
But it isn’t really the book-like presentation we have with gitbook

3

Thanks for highlighting Resonate’s use of Discourse.

Plus side: familiar tools, self-hosted, libre; simple-seeming; keeps our media together in a single tools frame, simplified UI for our users.

Minus side: more limited layout and navigation options than gitBook (not sure about nesting of content for example, the gitBook does a lot of that sections/main topics/subtopics); lack of book-like UI.

Worth an experiment. I might try it with our current strategy documentation?

Resonate have put a nice ‘skin’ for their Discourse instance. Would be good to do that too.

4

In social.coop Agaric posted about Drupal/Drutopia. So I asked if that tool is good for building a handbook rather than just ’ a website’.

I suspect the shortcoming will be navigation options. Which matter a lot I feel, for a systematic reference/FAQ document collection. Basically, requires a nested sidebar, showing sections, subsections, chapters, maybe sub-chapters. Very few platforms seem to offer this, and typically, not website templates. But gitBook does. The ‘booklike’ format matters?

Agaric mentioned ReadtheDocs, used for the Dutopia handbook.

5

@wouter responded:

About ReadtheDocs, I think it’s a clean tool, looks good for documentation used by so many, though not with a book structure, still a decent ToC. Now Read the Docs has variants, that I recall from our previous exploration, like MkDocs, see here its docu: Getting started with MkDocs — Read the Docs user documentation

6

It’s time to try developing handbook content in Discourse. using plugins

If you have experience of these plugins, would be good to hear from you - pros and cons?

7

The subcategory Handbook (now Handbook old) is superseded 12jul2022 by a new main category: Handbook https://forum.meet.coop/c/handbook/43. However, this thread remains open to explore Discourse as a frame building a handbook.

8

I’ve installed this component. It can be seen to work here and configured here.

9

The above mentioned Category Sidebar component does what it promises: it presents the content of a specific page in the sidebar of a defined category. That’s useful.
Another thing is to have a menu sidebar where (selected) categories can be made into a sidebar menu to help navigation. That’s what they have done at Resonate, as @Hakanto explains here. One part of it is the Category Sidebar Widget, developed by Pavilion (they have contracted with them in the past to help them set up/customise their Discourse forum.

Sidebar

The sidebar we use is made by Pavilion. It’s called :card_file_box: Category List Widget - Layouts - Pavilion . Since we use our forum as a workspace, this is very helpful. Highly recommended
Apparently this isn’t an official Discourse forum, unfortunately, but if it is a valuable tool, we can install it manually.
Handbook #toolstack #discourse

10

About Discourse and the number of category levels, here’s the confirmation from the meta.discourse forum:

Discourse has categories and sub categories; it does not support an indefinite level of sub-categories. You can approximate more levels with tags.

I have activated the “tags on topics” option in the settings. See an example in the FAQs subcategory, you’ll notice a tags dropdown and see tags inside the thread.You can also link to all threads with a certain tag, like this one: SSO. It seems a straight forward way to use tags?

11

We’d also need to explore the theming. We’re using the Light theme (the default one?). Themes allow certain customisations. For example I see that the category & tag navigation could be located as a vertical menu (instead of the current horizontal one), like here in this example with the Topic List Sidebar Navigation.

Or we could keep it horizontal but see what can be customised in the presentation of the cats. Adding an image would do wonders :wink: Personally I like the holo.host forum quite a lot, as a simple customisation on top of the default discourse (or so it seems - I could ask the admins if interested)

1 Like
12

Tagging
I think using tags as fake categories isn’t good discipline, but may have to do, it seems. It would be good to have categories serving one purpose (identifying areas of content, within ‘an ontology’ or map of the world) and tags serving another (identifying relationships that a reader might want to have with that world - ‘pathways’ or ‘roles’).

So I think using tags-as-subcategories should be done with moderation, perhaps only where ‘a second level’ of subcategory seems essential? Keeping tags as pathways might be the main intention?

However - this nice distinction goes all to pieces, when tagging is open to all topic-creators? The work of moderators could be endless! Even so, I feel we should try that approach. ‘Reader-tagging’ (aka self-mapping of published content) is one of the fundamental requirements for digital tools for organisers, I would say (see toolstack Mapping & navigating trio). It would be great if Discourse allowed a reader to create their own world of tagged content in the browser. But that’s beyond its aims? So enabling author-tagging is as near as we can get?

The effects may vary according to which segment of the forum? Revised structure In the segment ‘ONGOING - Comments & deliberations’ it seems fair to enable tagging by all topic-creators. Maybe moderating new topics isn’t too much hard work.

In the segments ‘RIGHT NOW - Help & news’ and ‘ONGOING - Board & Handbook’ it might be good to limit who can tag a topic, since these are mainly ‘publishing’ channels for the coop. But within these, the ‘Stewarding’ category, for example, should enable tagging by any Board members and Ops members. This is all a bit more complex, in terms of social relations, than Discourse is designed for! Let’s see how reader-tagging works and how much moderation work it generates?

On principles for tags (three kinds of tags), see the suggstions here: Tags

13

FYI I keep a list of links related to this design topic here Building a handbook in Discourse? - HackMD

14

Yep . . . . . . . :slight_smile:

15

@Hakanto left some thoughts in a private thread a couple of days back :smiley: . Here they are reposted:

===

I approach designing each category as a place you go to do a defined activity.

  • “I go to the Proposals category to make a proposal or explore other proposals.”
  • “I’m part of the Ops Circle so I go to the Ops Circle category when I want to collaborate with the rest of the circle on our work.”
  • “I go to the Music category when I want to chat about music.”

If the activity of a certain category is facilitated by or dependent on an individual or group, that entity should be defined as a user group and their responsibility to that category should be clearly posted.

  • Bad: “I shared an idea in Proposals… and nothing happened. Other users seemed excited about it, but then the topic sat there for three months. No one said anything and then I left.”
  • Good: “I shared an idea in Proposals… and nothing happened. It says that the @opscircle is responsible for vetting proposals and to @ them or send a message if a proposal seems to have stalled. Maybe they are just busy or need help… i’ll send them a reminder.”

Across categories, themes can connect via tags. Tags are like subway tunnels between places.

  • “Ah, I see that this Topic in Proposals is tagged democratization. I’m interested in that. I wonder where else that tunnel leads?”
  • “Hmm, this Proposal topic is tagged complete. I wonder what other proposals are complete?”

Some guidelines that have helped me:

  • Categories shouldn’t overlap much in terms of their activities
  • Each activity you are inviting people to do (and those responsible for it) is clear in its respective category
  • The highest level categories are the activities you want to encourage nearly everyone to do
  • The subcategories are usually specialized activities for a specific audience or working group

A good exercise is to go through each category you are considering and write a user story for it:

  • “As a member of the ops team, I want a forum category where I can work asynchronously with my teammates, so that I can have longform conversations about work items, rsvp to team meetings, and know that all my work is in one place.”
16

A further reposted comment from @Hakanto:

I don’t believe Discourse is a substitute for a real-time chat service like Mattermost, RocketChat, or Slack. The Pavilion, a worker co-op which builds Discourse forums, doesn’t try to use it that way either. They use Mattermost.

We recently set up a Mattermost at Resonate (specifically for work contributors to collaborate with each other, not a general chat area). The benefits have been immediate. Discourse PMs aren’t transparent “channels”, they are private messages. If you try to use them as chat channels, expect communication to decrease and coordination to be cumbersome.

17

In Mastodon, @wouter posted:

“BookStack is an open source, web-based documentation system, that allows you to create a structured knowledge store for personal, team, or company use”: Document with BookStack, an open source Confluence alternative

@mikemh responded:

#bookstack does look interesting thanks. But how to achieve ‘try b4 you buy’? Right now I wouldn’t want to ask our admins to add it to their hosting roster. And b4 I invested in either loading an instance with content, or asking admins to host it, I would want a good trial with it. Yes there is a demo. But not a hosted option anywhere I can see, for a pilot implementation? Out of which, content might be ported to a self hosted instance?

A core limitation of #bookstack - only three levels of nesting: book/chapter/page. Somewhat artiificially, to gain maximum depth of nesting within that structure, any document must be organised into multiple ‘books’. I’m not excited being forced into this kind of mental gymnastics.

Also tagging as such isn’t supported. (‘Tags’ in bookstack are internal codes used for text manipulation.) The equivalent of tags seems to be ‘bookshelves’. Any book can be on multiple ‘shelves’. Only book-level units can be tagged?