Writing effective how-to documentation

[Discourse]

This guide provides instructions on writing effective how-to documentation for Discourse. It covers essential elements such as structure and style, audience consideration, and maintenance.

Required user level: Anyone can write new how-to guides

Writing effective how-to documentation is crucial for helping users, moderators, administrators, and sysadmins perform various tasks within Discourse. This guide will help you craft clear and valuable how-to guides for the community.

Summary

In this documentation, you’ll learn:

• Why writing a how-to is important
• What information should be included
• Guidelines for structure and style
• Where to post these topics
• How to maintain them after posting

Why write a how-to?

Have you ever needed to perform a task and couldn’t remember how to do it? Writing a how-to document is an excellent way to document processes in Discourse. If you’re struggling with a particular process, chances are someone else is too. Documenting it helps everyone.

Learn more about what makes a how-to different from other documentation types like tutorials or reference guides in this guide from Divio.

Writing or reviewing a how-to is a great way to start contributing your knowledge of Discourse to the community. For other ways to contribute, check out the guide on how to contribute to Discourse.

What information should be included?

A how-to should be a step-by-step guide driving the user to a specific end result. For example, a how-to titled “Setting up HTTPS for Discourse” should provide instructions for setting up HTTPS.

Key points to remember when writing a how-to guide:

• Stick to the topic and be clear
• Avoid unnecessary information
• Be concise yet informative
• Explain why achieving the end result is beneficial

Consider your audience

There are different audiences for Discourse how-tos, each requiring a different depth of explanation. Use the documentation categories as a guide for who to target with your guide:

• Using Discourse
• Site Management
• Integrations
• Hosted Customers
• Self-Hosting
• Migrating to Discourse
• Developer Guides
• Contributing

Understand the technical skill level of your audience and tailor your guide accordingly. Some tips:

• Avoid steps the audience cannot perform (e.g., hosted customers generally don’t have access to console commands)
• Keep instructions clear and avoid highly technical language for non-technical users
• Don’t add background information that your audience should already know

Structure and style

The documentation style guide covers everything you need to know about how to structure and style how-to guides (and all other Discourse documentation):

Documentation style guide

This is considered a living document that guides how Discourse documentation is written and formatted. This topic will be kept up to date as needed. If you are in doubt about any of the principles here, please post on the topic to discuss specifics. The guiding principle behind these guidelines is to consider your readers and their needs when writing documentation - what do they want to accomplish? What is your goal for providing the content? Meta information Document should belong to one a…

Posting a guide

Post guides in a subcategory of the parent Documentation category and tag them with how-to. All guides need approval from the Discourse team, which will be handled through the moderation process automatically. The style guide describes each category in more detail to help you decide where your guide should be posted.

Maintaining your guide

Once you’ve posted a how-to, keep it up to date. Here’s how you can help maintain it:

1. Watch for replies — Integrate community feedback into the guide.
2. Test the guide yourself — Go through the guide periodically to ensure it’s still accurate.
3. Edit missing or incorrect information — If you’re at Trust Level 2 or above, edit the first post of the how-to.
4. Flag topics for assistance — If you can’t make an edit, flag the post with “Something Else” and explain what’s needed.

In most cases, official how-to guides will have comments deleted after a month to keep the focus on the guide itself.

---

Thanks for improving the Discourse community documentation! If you’re stuck, don’t hesitate to ask for help. The best way to start is by contributing and learning as you go.

Last edited by @hugh 2024-06-11T04:10:14Z

Last checked by @hugh 2024-06-11T04:10:19Z

Check document

Perform check on document: