Explore more topics

Write articles for the Knowledge Base

As a knowledge base contributor, you use words to help half a billion users. That's a big job. Users come to the knowledge base from all over the world, and they expect easy solutions, but we also want to delight them with our voice. How do you do that? Here are some things that we came up with in our research.

Tone

Write with the brand in mind. Mozilla is about user choice. We believe in freedom and flexibility. We value privacy and security. We are a community-driven non-profit with contributors all over the world who share common values.

You don't need to hammer this story in every time you write an article. It's just something to keep in mind when you're describing features.

Writing style

Write for a general, non-technical audience.

We want our articles to be usable by everyone, not just advanced users. This means we're writing for a general audience rather than one very familiar with computer techniques and terminology. Assume the person you're writing for doesn't know how to change preferences or add a toolbar button without step-by-step instructions. Also, we should assume that they haven't changed any of the default application or operating system settings.

To summarize, you should follow these guidelines:

Keep it short. People come to the knowledge base looking for quick solutions. They might not care about the inner workings of the tool -- they just want to know what they should do to fix it. Go ahead and chop off some words. See how much can convey with fewer words. It's like poetry!

Keep it clear. Avoid jargon. Be specific. Use words in the title and in the article that the reader would use. If your 13-year-old nephew won't understand it, write it so that he would. See the next section for a more extensive guide.

Be friendly, fun and empathetic. (In short: Be human). Okay, so users don't come to support expecting fun. That's what makes this powerful. Brighten up the user's day with a little humor. But be careful not to sacrifice clarity by using fun metaphors or expressions. If you're not sure how to balance this, just write straightforward instructions and use the tone in the introduction or conclusion.

Tell a story. Have a beginning, a middle and an end. But don't write a novel (see guideline #1).

Beginning: this gives the reader some context. What is this article about and why should I care? Keep it short.

Middle: The instructions go here. This should answer "How do I do this?"

End: Are there any next steps to the article or feature? Tell the reader where he or she should go next if they want to learn more.

Read the next section for more comprehensive guidelines.

Writing style (comprehensive)

Conversational writing style – Use an informal, active style similar to the way you'd speak to someone in person.

Humor and emotion – Using humor is great but it's sometimes hard or impossible to localize. Emotions like surprise and "I didn't know that!" (not sure what to call that emotion) might be easier to include.

Multiple learning styles – Just like in school, people learn differently. Also, everyone benefits from seeing the same content expressed in multiple ways.

Repetition – When you explain something in a different way with different media, you're also, obviously, repeating it which is another good way to help people remember what's important.

Images and video – Using images and video to explain things along with text is not only the next best thing to being there to help in person, they are an easy way of including multiple learning styles and repetition.

Activities – Especially in a tutorial, it's good to give people something useful to accomplish. It's one thing to read instructions and understand the process, but it's often helpful to remind and enable people to try things out.

Write a good introduction

Along with the title and the table of contents, the introduction is what people will use to quickly determine if they are in the right place.

For a tutorial or how-to article: Give a brief summary of what things can be learned.

For a reference article: Give a brief explanation of the feature.

For a troubleshooting article: Give a brief summary of the problem and its symptoms.

A good introduction can usually serve as a good search summary. Often you can just copy it into the "Search result summary" field and you're done.

Organize the article effectively

The general idea here is to try to 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.

Use descriptive heading titles

Our articles are usually comprehensive so it's important to use descriptive headings to help people find the part of the article that they need. Take a look at your table of contents. Does it work with the introduction to give you a nice overview of the scope of the article?

Make step-by-step instructions easy to follow

The main thing to keep in mind when writing step-by-step instructions is to be careful to include all the actions needed to complete the task. If, for example, you have to click "OK" after selecting a preference in order to move to the next step, be sure to include clicking "OK" as part of that step.
Some additional things to consider:

There are always multiple ways to achieve a result. We should always pick the most user-friendly way by using the graphical user interface and menus when possible.

Use full sentences when describing how to access the user interface.

Include expected results when giving instructions (for example, Click "OK" and the window will close.).

Title

Title length: Google's search results page will display up to 70 characters. Your title can be longer than this if necessary but make sure your important keywords are included in the first 70 characters.

Do not use a colon in the article title since it prevents creating a wiki link to that article (bug 749835). Also make sure you don't have extra spaces in the article title, which will also prevent wiki links from working.

Try to vary the way you name articles. Don't use the same verbs or phrases in every title. For example, don't always start articles with "How" and avoid using "-ing" words.

Remember that the entire explanation doesn't have to go into the title. You can use the summary to give the user additional information about what is in the article.

Fix the slug

When you create a title, SUMO will automatically create a slug (the end of the URL for the article). The slug has a 50 character limit. Spaces are rendered as dashes. The slug should be consistent with the title, but given the tighter space restraint, doesn’t need to be the same. Be sure to check the end of the auto-generated slug. Sometimes a word gets cut off or it ends in a dash. Please fix things like that.

Categories, products and topics

For the most part, an article belongs in either the How-to or Troubleshooting category. Occasionally we write "How To Contribute" articles (like this one) or something in one of the other categories.

Articles are also "relevant to" at least one product. They also belong in one main "Topic" and, optionally, a "sub-topic".

Write a good search summary

The article summary along with the title are the only things that the user has to judge whether or not an article will answer their question. We call this "User Confidence" and it directly impacts click through rates. Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display in order for them to click through to the article.

A summary for a how-to article should include the topics covered in the article. A troubleshooting article should try to include symptoms. In addition, a summary should follow these guidelines:

Short and to the point. Remember classified ads? Write it like that. Search engines may cut off anything longer than 140 characters. If you use a longer summary, keep the important information at the beginning. Note: The KB software will show 20 characters remaining when the summary reaches 140 characters because the internal search limit is 160.

Don't use wiki markup.

Don't use "This article explains" in every summary. Vary it when possible. Some other phrases to consider:

We'll show you

We'll explain

This page explains

This article describes

Learn how

Style guide and copy rules

Like we said before, you should use an active, conversational style when you write. 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 and copy issues you may run into when writing support articles (if you don't see your issue here, there's also a Mozilla Style Guide):

Always use terms the way they appear in the Mozilla interface. For example:

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

Don't use "i.e." and "e.g.". These Latin abbreviations can confuse people. For the sake of clarity, use "in other words" or "to put it differently" instead of i.e. when you want to explain something in a different way. Use "for instance", "for example" or "such as" instead of e.g. when you want to give examples.

Don't use serial commas in a list of items. For example, use "Extensions, themes and plugins" (without the serial comma), not "Extensions, themes, and plugins".

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.

We have a special wiki markup – {for} – that allows you to target information for specific versions of Firefox or specific operating systems. For example, you display one set of instructions to people running Windows and another to people using Mac OS X (see How to use For for details).