How to write a #how-to

A #how-to is an essential part of community knowledge for Discourse. How-tos inform users, moderators, admins, and sysadmins alike to perform basic → advanced operations concerning Discourse.

In this guide, you’ll learn:

  • Why write a #how-to?
  • What information should be included?
  • What guidelines are there for structure and style?
  • Where do these topics get posted?
  • How is it maintained after it is posted?


Why write a how-to?

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

First and foremost, a how-to is a process document. Writing a how-to, 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.

:bulb: Learn more about what makes a #howto different from other kinds of documentation like a #tutorial or #reference guide in this guide from Divio.

Writing or reviewing a how-to 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 included?

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

For example, a how-to 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 how-to.

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 how-to 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 how-tos, with a subcategory for each:

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:

  • Don’t include steps the audience may not have access to.
    Admin guides should not include console commands, and user guides should not include site settings.
  • Don’t be highly technical if the guide is for new end users.
    Focus on clear, concise steps, and include screenshots where applicable
  • Leave background information your audience must already know
    If you’re writing for a technical audience about making a change to a config file, don’t include information about how to open a text editor or save a file; focus on the precise information that should be changed in that file.

Structure and style

How-tos 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.

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 document down into sections using headings.

Use ordered numbered lists for procedures that include many small steps. Use unordered bullet lists for separate pieces of information that are not part of a procedure.

If there’s a piece of information you need to stand out, use 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:

  • :information_source: - An informative note
  • :mega: - Announcement or notice
  • :warning: - A warning message
  • :exclamation: - Very important information

Add a small number of 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.

Use codeblocks for text that needs to be copied.

This is most relevant for sysadmin how-tos, 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.

Keep it concise

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 how-tos are short, there are some examples of well-written long how-tos, like this one: Beginner's guide to developing Discourse Themes

If your how-to 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 how-to. 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

Guides all belong in a subcategory of the parent #documentation category, and should be tagged with #how-to.

Guides will need to be approved by the Discourse team before being made public. This will be handled by our moderation process automatically.

Reviewing and maintaining a guide

Once you’ve posted a how-to, 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 how-to 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 how-to 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 how-to guides will have their comments automatically deleted after one month. This is to help keep these topics focused on the how-to 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.