This image breaks down the parts of a knowledge base article into color-coded sections. You will see what the article looks like live and what it looks like in the editing tool.

• The red line at the top shows the article’s title. We don’t write out the title in the wiki markup page. They write the title in the article’s description section. Here you find more information about categorizing articles.
• The orange section shows the header. Notice how in the wiki markup section the header is surrounded by two equal signs.
• The yellow section contains the introduction. It’s helpful to add this so that readers know what the article is about and what they can learn by reading it.
• Green shows the first step. Notice how in the wiki markup the individual steps are distinguished with hash symbols.
• Blue contains a screenshot. Screenshots are crucial for illustrating concepts in articles. Readers may not understand a concept if they can’t visualize it. Notice how the wiki markup designates a screenshot with an image name. Find out how to make screenshots here.
• The purple box contains a note with additional information. Notice how this section is surrounded by a note notation.

Detailed information about each section

This section breaks down the anatomy of a knowledge base article. 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" article intros: A brief summary of the feature or task and what things can be learned (example).
• Troubleshooting article intros: A brief summary of the symptoms and the solution (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.

For example, in this Tab Groups article we start with why you should use the feature, then move on to how to make a group and finish with more complicated tasks like searching and organizing.

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 a tab with the web page you want to use as your home page.
2. Drag and drop that tab onto the Home button .

   

3. Click Yes 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 and Mac instructions to Mac users. If you switch the operating system at the top of this article, the appropriate steps below will change according to the selected operating system.

Use templates in your step-by-step 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 single steps a lot. Here are the same steps as shown above but this time written by using templates.

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. Select the General panel.
3. In the Startup box under Home Page: click Restore to Default.
   
4. Close the Settings page. Any changes you've made will automatically be saved.

More information

• All wiki markup symbols can be found in the Markup chart.
• To learn how to create an article step-by-step, click here.
• Learn how to use the For function and templates.
• Learn how to categorize an article with an article's description.
• Learn how to edit articles by looking through an article's history.