# Building a handbook in Discourse? https://hackmd.io/@meet/SJnkckHP9 Aka rebuilding the meet.coop forum Notes by : mike hales * Handbook [**requirements**](https://cloud.meet.coop/s/xGyTYopFcTKRp62) @ NextCloud * **Categories, tags** and the (re)structuring of the forum: fedwiki pages by mh [**forumcats**](https://forumcats.wiki.cafe/view/original-structure/view/categories--tags/view/revised-structure) * [Handbook trial](https://meet-coop-1.gitbook.io/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](https://community.resonate.is/docs?category=) * A comparator - [**Holo host**](https://forum.holo.host/) Discourse site ### Discourse tooling aka plugins * [Plugins](https://meta.discourse.org/docs?tags=plugins) @ Discourse meta * Customisations of Discourse by [Pavilion](https://thepavilion.io/c/knowledge/discourse/171). See below: *Pavilion Layouts vs Discourse plugins*. --- #### Current and potential plugins * The most significant missing navigation tool? [Table of Contents](https://meta.discourse.org/t/discotoc-automatic-table-of-contents/111143). Install this? * There’s a [Topic list sidebar](https://meta.discourse.org/t/topic-list-sidebar-navigation/94056/) 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**](https://meta.discourse.org/t/sidebar-with-categories/104165) within a discovery page. Do we use this? I don't think so. * We’re using [Header menu/submenus](https://meta.discourse.org/t/header-submenus/94584). Are we making enough good use of this? * We’re using [category sidebars](https://meta.discourse.org/t/discourse-category-sidebars/107561) 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](https://meta.discourse.org/t/discourse-tag-sidebars/111114) 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](https://meta.discourse.org/t/discourse-tag-cloud/218014) plugin Maybe the existing [**tag list**](https://forum.meet.coop/tags) is sufficient? Would a tag cloud offer anything extra? * [General intro](https://blog.discourse.org/2017/10/its-time-we-talked-about-tags/) to tags vs categories. --- * There’s a [discussion **here**](https://meta.discourse.org/t/new-theme-tag-pages-navigation/131263) 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**](https://forum.meet.coop/tags). > > Resonate has [a million tags](https://community.resonate.coop/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](https://forum.meet.coop/tags)), 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](https://forum.meet.coop/tags) * Maybe, with ['structured tagging']([xxx](https://meta.discourse.org/t/set-up-structured-tagging-with-tag-groups-and-category-tag-restrictions/48260)) 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**](https://meta.discourse.org/t/administrative-bulk-operations/118349) 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**](https://community.resonate.coop/c/helpdesk/handbook/guides/77) (Guides/Roles/Policy) in their **handbook**, under **Helpdesk**. See also [**here**](https://community.resonate.coop/t/using-the-product-backlog/3165) 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**](https://forum.holo.host/) Discourse site, which is very clean? But only two levels, and not a lot of content. [Discourse meta](https://meta.discourse.org/t/how-many-subcategory-levels-discourse-allows/26198/2) 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**](https://forumcats.wiki.cafe/view/original-structure/view/categories--tags/view/revised-structure) 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](https://meta.discourse.org/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'**](https://meta.discourse.org/t/set-up-structured-tagging-with-tag-groups-and-category-tag-restrictions/48260) 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](https://discourse.pluginmanager.org/t/using-the-layouts-plugin/289), [widgets](https://discourse.pluginmanager.org/t/widget-settings/277). 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**](https://hackmd.io/OTUN2h5KQHuRz2JJBDEmCQ?both) * Lenses = [**Tags**](https://forumcats.wiki.cafe/tags.html) * [Using Discourse to build a handbook](https://forum.meet.coop/t/using-discourse-to-build-a-handbook/884/6) - **thread @ forum** * Pattern language [**template** for handbook protocols](http://e2o.federated.wiki/view/welcome-visitors/view/a-template-for-a-pattern/view/pattern-languageing-as-a-dance-of-knowing-for-the-college) @ e2o #### Prototyping & designing forum categories * [**Revised structure**](https://forumcats.wiki.cafe/revised-structure.html) of the handbook = categories/subcategories in fedwiki * [**Designing**](https://forumcats.wiki.cafe/view/welcome-visitors/view/forum-categories/view/original-structure/view/revised-structure) forum categories & tags in fedwiki #### mh related in wiki * [Rosters @ mhresources](https://mhresources.wiki.cafe/view/welcome-visitors/mhresources.wiki.cafe/resources/view/wiki-literacy/view/rosters) * mike - [bft @ wiki.cafe](https://bft.wiki.cafe/view/welcome-visitors/view/what-goes-on) * [learnstack](https://learnstack.wiki.cafe/view/welcome-visitors/view/learning-space-and-toolstack/view/trinity/view/extended-trinity)