How to write a #howto

A howto is an essential part of community knowledge for Discourse. Howtos inform users, moderators, admins, and sysadmins alike to perform basic → advanced operations concerning Discourse.

In this guide, you’ll learn:

  • Why write a howto?
  • What information should be in a howto?
  • How should I structure and style a howto?
  • Where do howtos get posted?
  • How do I maintain a howto after it is posted?


Writing a howto

Why write a howto?

Have you ever encountered something you need to do, but can’t remember how to do it? Write a howto!

First and foremost, a howto is a process document. Writing a howto, then, is a way to document how to do something in Discourse. If you’re struggling to remember a process, likely someone else is, too. Documenting it, then, will help everyone out.

Writing or reviewing a howto is one of the best ways to get started contributing your knowledge of Discourse to the community.

For other ways to contribute, check out the How to Contribute to Discourse guide.

What information should be in a howto?

A howto should be a step-by-step process guiding a user to an end result.

For example, a howto titled “Set up HTTPS for Discourse” should… instruct how to set up HTTPS!

The guide should be filled with relevant technical and/or process information which helps the individual accomplish the stated goal of the howto.

Don’t add unnecessary information. Don’t be long-winded. Be as clear, concise, and helpful as possible.

It also may be helpful to describe why the particular howto is helpful – why would the reader want to achieve the end result of the guide?

Be sure to consider your audience!

There are four main audiences for Discourse howtos:

  • Users
  • Moderators
  • Admins
  • Sysadmins

Each audience has different needs for how in-depth your process explanation should be. Be aware of the technical skill level of the audience your guide is for, and write the guide accordingly.

Some tips:

  1. Don’t be highly technical if the guide is for new end users. Instead, focus on clear, concise steps with lots of screenshots.
    • State exactly which buttons to click and where to get to the desired end result.
  2. If you’re writing out complex sysadmin guides for advanced Discourse configurations, don’t feel the need to spell out every single detail.

Howto structure and style

Howtos for Discourse don’t need to adhere to a strict documentation standard, but they do need to be helpful, clear, and concise. Here are some structure and style considerations to make when developing a guide.

1. Use headings, lists, and blockquotes.

Structure is your friend when attempting to make your guide readable. If your guide is longer than a few hundred words, break your writing down into steps using at least ordered or unordered lists, if not headings.

If there’s a piece of information you need to stand out, a great way to do this is by using a blockquote with an emoji.

This technique is useful if you need to call attention to a specific case a guide is used for, or if there’s a piece of information that must be considered.

Common emojis used:

  • :mega: - Announcement or notice
  • :warning: - A warning message
  • :exclamation: - Very important information

2. Add screenshots where applicable.

A picture is worth 1,000 words – and this is all the more true with technical documentation. If doing something isn’t 100% clear from words alone, include a screenshot. Screenshots are also helpful for assisting our non-English users, as there may be challenges relying on text alone.

Do be aware that sometimes screenshots get out of date, and as a result, need to be updated in the future.

3. Use codeblocks for text that needs to be copied.

This is most relevant for sysadmin howtos, but if there are steps that require the reader to copy a command, be sure to use codeblocks.

The best approach is a full codeblock using three backticks: ```

This also includes a copy codeblock button on Meta so the entire block can be copied easily and automatically to the clipboard.

4. Keep a reasonable length.

A guide should be no longer than it needs to be, but long enough to clearly communicate to the reader what, how, and why.

While most howtos are short, there are some examples of well-written long howtos.

If your howto is a broad guide, like the one linked above, there are two considerations to make:

  1. If the topic is meant to be a one-stop resource, be sure to break down the guide into digestable sections with headings. Each section should be as short as possible.
  2. If the topic covers a broad number of differing areas, stop and consider writing each area as a separate howto. If those guides are approved, it may make sense to come back and create a topic linking to all of the related guides.

Posting a Guide

Howto guides all belong in a subcategory of the parent #howto category.

Guides being posted to official howto categories (admins, devs, faq, sysadmin) will need to be approved by the Discourse team before being made public. This will be handled by our moderation process automatically if you post to an official howto category.

Guides posted to community howto categories (tips-and-tricks) do not need review, but should do their best to adhere to these recommendations.

Reviewing and maintaining a howto

Once you’ve posted a howto, it’s important to keep it up to date. While the Discourse team helps with maintaining official guides, you can assist, too!

Here are some things you can do.

  1. Watch for replies – Often, some of our best feedback on howto guides comes from the community in the form of replies to the topic. If something is wrong, feel free to fix it!
  2. Test the guide out yourself - If a guide hasn’t been updated in quite a while, try going through it yourself.
  3. Edit missing/incorrect information - If you are at TL2, you should be able to edit the first post of a howto as a wiki. If information is missing or incorrect, edit it in!
  4. If you need assistance making a change, flag a topic Something Else - Sometimes you’re not sure of an edit or you aren’t able to make it yourself. In that case, flag the first post of the topic as Something Else and our team will assist. Be sure to state what needs to happen and why.

In most cases, official howto guides will have their comments automatically deleted after one month. This is to help keep these topics focused on the howto versus supporting the community.

If you’re interested in helping integrate feedback and changes from these comments, pick a category to set as Tracking, then any time a post is made, evaluate if edits are needed to the OP.

Thanks for taking the time to consider improving documentation for the Discourse community! If you’re stuck, don’t be afraid to ask for help! The best thing you can do is just start contributing and grow from there.