HackMD
Building a handbook in Discourse?
https://hackmd.io/@meet/SJnkckHP9
Aka rebuilding the meet.coop forum
Notes by : mike hales
- Handbook requirements @ NextCloud
- Categories, tags and the (re)structuring of the forum: fedwiki pages by mh forumcats
- Handbook trial @ gitBook. This content is now being migrated to the Discourse forum, preparing to shut down the gitBook account. Temporary storage in an Obsidian repo in meet.coop Nextcloud.
- A comparator - Resonate handbook
- A comparator - Holo host Discourse site
Discourse tooling aka plugins
- Plugins @ Discourse meta
- Customisations of Discourse by Pavilion. See below: Pavilion Layouts vs Discourse plugins.
Current and potential plugins
- The most significant missing navigation tool? Table of Contents. Install this?
- There’s a Topic list sidebar that we haven’t considered. It puts the topic selection tools from the 'discovery' page of a category, in the sidebar of every page. Would this help navigation? I'm not sure that it would.
- There's a sidebar plugin that displays categories within a discovery page. Do we use this? I don't think so.
- We’re using Header menu/submenus. Are we making enough good use of this?
- We’re using category sidebars which display a category-description page. We haven’t yet got the content right for these. Effort on that would be worthwhile?
- We also have tag sidebar plugin that will display a tag description page. (This is basically similar to the category sidebar that we haven’t mastered yet).
Tags vs categories
- The tag cloud plugin
Maybe the existing tag list is sufficient? Would a tag cloud offer anything extra? - General intro to tags vs categories.
- There’s a discussion here of tags vs categories for navigation (heavily in favour of tags). But it seems to have fizzled, and no plugin got built.
NOTE: its focus is on user-tagging (of public discussion/comment topics). Whereas, I feel that it’s admin tagging that we need: a limited and stable repertoire of reader's-purpose oriented tags (to assist navigation 'routes' thro Discourse), as distinct from an endlessly expanding repertoire of topic-content tags. For tag/category design rationale, see this wiki lineup.
Resonate has a million tags, for example. I don't think this helps a lot. Also, they're not making use of tag groups. We do this in a limited way (see here), but we should do it more, it identifies the different classes of tags? However, there seemed to be some snag in this (can't quite recall what it was) so I stopped using them at a certain point.
Update: I recreated tag groups. bcos it does seem a helpful way to view the list of all tags
- Maybe, with 'structured tagging' users can add some tags, but 'official' tags by admins can be viewed separately, to keep the navigation tags clean. We might need to use tags for nesting of topics too, within the Handbook. See below: 'Levels of subcategories'.
Levels of subcategories
There's a sidebar being used here that displays heading levels within a (very long!) page. This seems to be a way of getting by without sub-sub-categories? Might we have to do this, in the handbook? That page looks OK-ish, we could get by with that kind of sidebar I wonder?
It would be better though (?) if we could create a further level of categories (or two), like Resonate seems to have. They have a third level here (Guides/Roles/Policy) in their handbook, under Helpdesk. See also here for example, which has three category levels and one tag.
How did they achieve that third level? Could there be more levels? I can't see this in the Discourse meta site. Hakanto doesn't seem to know how this was achieved for the Resonate site. Would Calix know? Do we know who built the Holo host Discourse site, which is very clean? But only two levels, and not a lot of content.
Discourse meta says "There are only two levels, after that, use tags". I'm not keen on using tags in that way, for content. I would like to see them reserved for readers'-role navigation (also referred to here as enquiry perspective. So . . long pages, with subheads and a subhead sidebar is the way to go? That's bearable?
So, we need to identify the plugin for this. Search the 'official plugins' tags in Discourse meta? Nope, nothing there :-(
If tags need to be used for nesting (as in the handbook), there's a discipline to this. This page on 'structured tagging' seems to cover the discipline. It rests on tag groups and restrictions on which tags can be used in the context of which other tags and categories. We should practice this?
Pavilion Layouts vs Discourse plugins
Pavilion offers Layouts, a system in which widgets can be displayed on pages, in sidebars. See: Layouts, widgets. We should (?) consider this as an alternative to numerous Discourse plugins? It's a single plugin.
Layouts has features including:
- specify the order widgets appear in the sidebar
- context-specific widgets
- widgets targeted to topic lists, topics & user profile (ie SSO)
- group-specific widgets (show different sidebar content to different users)
- allow the user to hide/show sidebars.
Should we evaluate these options? Could this be cleaner than multiple Discourse plugins?
Other
- mh early thoughts on handbook/FAQ tool frameworks in markdown
- Lenses = Tags
- Using Discourse to build a handbook - thread @ forum
- Pattern language template for handbook protocols @ e2o
Prototyping & designing forum categories
- Revised structure of the handbook = categories/subcategories in fedwiki
- Designing forum categories & tags in fedwiki
