This video introduction gives you some context for the following article and a brief overview of what's in it. By watching the video you can quickly determine if this is the right article for you.

You want to learn how to write help articles for Mozilla Support? This article shows you examples of our most common writing techniques and important wiki markup. You can use both the article and its wiki source as a guide when you write an article.

In general, we have two basic types of articles with two kinds of introductions:

• Tutorial or "how-to" articles: A brief summary of the feature or task and what things can be learned (example).
• Troubleshooting articles: A brief summary of the symptoms and possible solutions (example).

How to structure an article

The general idea here is to try and build skills from simple to complex while trying to keep the information needed by most people near the top. So a simple, common solution would usually come before a complex or edge-case solution.

Write descriptive section headings so readers can scan through quickly

Naming the section header after the task or the solution allows the reader to quickly browse the article or scan the table of contents to see the scope of the article. In some cases this may already provide enough information for some users and they wouldn't even need to read the rest of the article.

Create step-by-step instructions

There's nothing more frustrating than to finally find the instructions you need and then get stranded while trying to follow them because the writer assumed you knew something you didn't. This is why we break our instructions down into complete, numbered steps. If you have to click "OK" at some point we even define that as a step.

Here's an example from the How to set the home page article:

1. Open the web page you want to use as your home page.
2. Drag and drop that tab onto the Home button on your toolbar.

   

3. Click Yes on the prompt to set this page as your home page.

Create instructions for different operating systems or versions of Firefox

Often Firefox instructions are different for the different operating systems. We have special wiki markup that shows Windows instructions to Windows users, Linux instructions to Linux users, and Mac instructions to Mac users. If you switch the operating system in the "Customize this article" box to the right, the instructions below will change according to the selected operating system. This example is from the Find what version of Firefox you are using article.

Click the menu button , click Help and select About Firefox.On the menu bar, click the Firefox menu and select About Firefox. The About Firefox window will appear. The version number is listed underneath the Firefox name.

Use templates in your instructions

There are a lot of common steps in Firefox articles. For these we create "templates" so that we don't have to write (and translate) them over and over again. Usually templates include instructions for all operating systems which simplifies and accelerates the writing of the steps a lot.

This example from the How to set the home page article includes a template that gives instructions for opening the Firefox Settings panel.

1. In the Menu bar at the top of the screen, click Firefox and then select Preferences or Settings, depending on your macOS version.Click the menu button and select Settings.
2. Click the Home panel.
   
3. Click the menu next to Homepage and new windows and choose to show the default Firefox Home page, custom URLs or a blank page.

Knowledge Base guidelines

For more guidelines on Knowledge Base contribution, see this page.