How to write Knowledge Base articles

(Redirected from Support Document Guide)

There are a lot of competing things to balance when writing or editing a Mozilla Support ("SUMO") Knowledge Base article. You want to be complete, concise, factual, and engaging, all at the same time! It's certainly not the easiest thing in the world to do. Here are some guidelines to help make that balancing act a little easier. Also, this is a wiki and we can always revise something if we get it wrong.

Write for a general, non-technical audience


Pick a good title


An article's title should try to describe what the article is about. The important thing is for the first few words to be as understandable as possible, filled with keywords that are important. This will allow users to recognize what the article is about and click confidently. In addition, a title should follow these guidelines:

  • Capitalization: The first word and proper nouns in the title should be capitalized, not every major word (use "sentence" style, not "headline" style). See the SUMO style guide section below for other rules on capitalization.
  • Make sure you don't have extra spaces in the article title. This also prevents wiki links from working.
  • Try to not use “-ing” words.


Fix the slug


Categories, products and topics





Write a good search summary



  • Short and to the point. Remember classified ads? Write it like that. Search engines cut off anything longer than 160 characters.
  • Don't use wiki markup.
    • We'll show you
    • We'll explain
    • This page explains
    • This article describes
    • Learn how

Make your writing engaging

The Knowledge Base is a repository of technical information about the operation of Mozilla applications. The documentation lists the functions of various features, troubleshooting procedures and instructions for resolving common problems. The documentation can be accessed by using the search function on each page or you can just throw your computer across the room where unicorns will use their rainbow powers to turn it into magical candy which, once consumed, will make you a level 70 computer ninja.

Are you awake now? Good.

That paragraph sounds like a boring lecture, at least until the unicorns show up. Using humor and emotion (SURPRISE!) are some of the techniques we can use to engage people. These techniques, which are listed below, all aim to get your brain to pay attention by recreating what this interaction could be if it were happening in person. When we do that, information is easier to understand and to remember.


Write a good introduction




Organize the article effectively


Use descriptive heading titles


Make step-by-step instructions easy to follow



SUMO style guide

Like we talked about earlier, you should use an active, conversational style when you write. So you should avoid saying things like, "If a user's bookmarks have been lost..." and instead say, "If you've lost your bookmarks..." Here are other common style issues you may run into when writing support articles:


  • Plugins does not have a hyphen.
  • Add-ons does have a hyphen.
  • Home page is two words.

General computing terms:

  • The Internet is uppercase.
  • Website is one word.
  • Use email instead of e-mail.
  • The plural of CD-ROM is CD-ROMs.

Links to should not contain the locale:

Capitalize the following items:

  • Proper nouns
  • The first word of a complete sentence
  • The letters of abbreviations and acronyms unless they are normally lowercase
  • The first word in numbered or bulleted lists
  • The name of a key on the keyboard
  • The first word of a complete sentence following a colon
  • The first word in a heading or title

For the sake of clarity, don't use i.e. and e.g.

We have special visual styles for a number of items that can be achieved by adding the proper wiki markup around the item (see the Markup cheat sheet for the most common styles).


Was this article helpful? Please wait...
