Recently, we’ve been making an effort to improve our documentation here on meta, with a focus on categorizing things in such a way that different users can find topics that are relevant to them, and ignore topics that are not.
We aim to have all documentation land in one of the following categories:
- users - common general usage
- moderators - moderating a community
- theme developers - developing themes and theme components
- admins - administering a Discourse site
- developers - developing Discourse features, plugins, and integrations
- sysadmin - self-hosted system administration
We plan to remove #documentation:faq and #documentation:tips-and-tricks at the end of this (but have started to tag some topics in the new categories with tips-and-tricks).
We also aim to tag docs with one of these classifying tags borrowed from divio per this earlier post:
Things don’t always fit perfectly. In some cases, we’re splitting up topics, and in others we’re just using the tag or category that fits best in its current state.
Some common changes we’ve been making to individual topics so far (we’re about 50% done now).
- Moving things from admins to sysadmin when they require console access.
- Splitting up #documentation:faq topics into topics for admins and topics for users.
- Moving topics from developers to theme developers when they are specific to developing themes or theme components.
- Updating topic titles to be more consistent
- Use imperative tense for topic titles (and removing “how to” from the title).
- Use normal sentence capitalization
- Formatting content with headings starting at H2
(Related: we’ve also enabled the Table of Contents for all docs topics)
In some cases, we’re making some changes to the content itself, but diving deep is not our immediate goal. In a future pass, we’d like to do things like:
- Incorporate content from replies into docs themselves
- Delete all replies
- Configure topics to delete replies after 1 or 2 months
Then, going forward, we’ll provide updated guidance about contributing new docs and maintain existing docs and update the following topics:
We may want to make more docs into Wikis or find new owners for docs when they are being maintained by someone other than the original poster, for example.
We also think there may be an opportunity here to make separate space(s) for folks to do more “show and tell” along the lines of some of the content that had been #documentation:tips-and-tricks. Making space for topics like these outside of documentation may allow for more room to have discussions about them among peers. But similar to what we’re doing now with documentations, perhaps it would be helpful to have separate spaces for sysadmins, admins, and developers for those discussions. What do you think?