Discourse documentation is the primary location for administrators, moderators, users, and sysadmins to find help with using Discourse and managing their sites.
While this documentation is robust and covers a lot of ground, there are some missing areas that we do not have documented yet. This is a great opportunity for the community to get involved in helping to refine this important part of the Discourse project.
We would love to see more people getting involved in creating documentation content for Discourse, and want to make it as easy possible for anyone to do so. To that end, below is a list of Discourse features or use-cases that we have identified as requiring new or improved documentation.
Documentation locations
Anyone of trust level 2 or above can create new documentation topics in Community wiki - this is the home for all community-contributed documentation content. If a topic in the community wiki is considered relevant or important, it may be moved to Documentation - the home for all official Discourse documentation. You can read the documentation policy for more details about that.
Badges for documentation contributors
Anyone who creates a new topic in the Community wiki category will automatically be assigned the bronze Scribe badge:
If the topic is considered valuable enough to move to the official Documentation category, someone on the Discourse team will do this manually, credit the original author in the topic content, and assign them the silver Ghostwriter badge:
Documentation that needs to be written
While we ultimately want to see every part of Discourse thoroughly documented, these are the areas we have identified with the most pressing need (crossed out items indicate topics that have been written since this post was first published):
- A general getting started tutorial for admins
- Custom topic redirects
- Explanation of what different user levels can do
- Social login options
- Post notices (official doc)
- More documentation about how trust levels work
- How to write a good feature request for Discourse (wiki topic)
- A reference for how Discourse markdown and formatting features look when included in emails
- User statuses
- Explanation of dark mode, how to select it, and how to enable switching (wiki topic)
- General documentation covering managing user preferences (wiki topic)
- Docs explaining how categories and hierarchy work in Discourse
- A general guide for topic settings
- A general guide about plugins - what they are, how they work, and how to use them
- Custom homepages
- Changing default categories and topics
- Using image grids in posts
- Post approval settings (wiki topic)
Some of these may require multiple topics to be effectively documented.
How to write documentation
In order to ensure Discourse documentation is as effective as possible, we have a style guide for how to write this content. While it would be helpful for everyone to follow the guide, if you’re contributing to Community wiki, it’s not a problem if you don’t stick to it completely. Any topics that are moved over to Documentation will be updated by Discourse staff to match the style guide as needed.
Interested?
Jump into Community wiki and start documenting today. If you want to discuss any of this, feel free to reply to this topic to talk about it.
Great to see these coming in!