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:

1. 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 you can convey with fewer words. It's like poetry!
2. 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.
3. 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.
4. 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/Eureka!” 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 along with text is not only the next best thing to helping in person, it's an easy way of including multiple learning styles and repetition. Too many images, however, can make localizing an article more difficult, so try to add images only when it is helpful to a step or concept. For example, for a step that is clicking a button, you could say “Click OK” instead of adding a screenshot of that button's dialog box.
• 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.

Article types

Using consistent content types for our knowledge base articles has many benefits including ease of navigation and improved clarity and organization, in addition to helping us create content more effectively. We are transitioning to categorizing external knowledge base articles into four types, each serving a specific purpose:

• About: These articles address “What is…” questions, providing essential information to help readers understand a topic.
• How-to: These articles focus on answering “How to…?” questions, guiding readers through the steps required to achieve a specific goal or procedure.
• Troubleshooting: These articles assist users in identifying, diagnosing, and resolving common issues they may encounter with a product, service, or feature by addressing “How to…?” questions related to problem-solving.
• FAQ: These articles contain concise answers to frequently asked questions on a single topic, which may not fit within other individual KB articles, providing a quick reference for common inquiries.

Start with an effective and descriptive title

A well-crafted title is more than just a label; it's a user's first point of contact with your KB article. A good title should not only grab the reader's attention, but also serve as a concise and informative preview of the article's content. When creating titles for SUMO, consider the following:

• Clarity and Descriptiveness: Match what the article is about and what the user is searching for. Be concise, yet user-focused.
• Keyword Inclusion: Incorporate relevant keywords to improve search engine visibility and help users find your article.
• Conciseness: Keep titles brief while still providing adequate information. Shorter titles are often more user-friendly. Try to keep titles around 60 characters
• Action-oriented: Use action verbs when applicable to indicate what users can do to resolve an issue or achieve a goal. Avoid using gerunds (words ending in “ing”) in titles to ensure they remain action-oriented. Avoid using titles containing “How to…”

Write a good introduction

Along with the title and the table of contents, the introduction is what people will help the user determine if they’re in the right place.

• For an "About" article:Provide a textual overview or definition of the concept and focus on why the user should care about it.
• For a "How-to" article:Provide a textual overview or definition of the task and focus on the importance or benefits of the task.
• For a "Troubleshooting" article:Describe the specific problem or symptoms users may encounter. Write in clear and concise language, avoiding technical jargon whenever possible.

Keep in mind that 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.

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.).

Readability

The text must be readable. To do this, you must:

• Split an article into small logical/semantic blocks with subheadings.
• Use numbered or bulleted lists.
• Write short or relatively short sentences.
• Avoid writing large paragraphs.

There is no limit to the amount of text. The more material, the better; however, you should not artificially expand it. Provide only useful, valuable and necessary information.

How to link to external documentation for third-party software

When creating or updating articles that involve actions within third-party software, such as operating systems or external applications, it's crucial to provide users with accurate and reliable information. However, including direct steps for this software in our articles can present challenges:

• Quickly outdated information: Third-party software updates can render our instructions obsolete, potentially confusing or misleading our users.
• Resource intensive: Continuously monitoring and updating steps for multiple external platforms would require significant effort and resources, which may not be feasible.

Best practices

To ensure our users receive the most reliable and up-to-date information without overwhelming our resources, follow these best practices:

• Link to official resources: Whenever instructions involve third-party software, find the official documentation or help articles provided by the software maker. Link to these resources instead of writing out the steps directly in our articles.
• Provide context: Briefly explain why you're directing the user to an external page (for example: "For the latest and most accurate steps to adjust your system settings, please refer to the official [software name] support page").
• Check links periodically: While we aim to reduce the maintenance of third-party instructions, periodically checking that external links are still valid is still important. If you notice a link has become outdated or broken, look for an updated link to the official documentation and submit a revision.
• Disclaimer on external content When directing users to an external link, make it clear that they will be leaving SUMO and that we're not responsible for the content of external sites. A simple disclaimer or note can suffice (for example "Following this link will redirect you to an external website that is not operated by Mozilla.").

Example

Imagine you're writing an article on configuring a Firefox feature that relies on changing system-level settings on a Mac. Instead of outlining the steps directly in the article, you might write:

"For the latest steps on adjusting your system preferences on macOS, please consult the official Apple support documentation by visiting this guide. Please note that following that link will direct you to an external website that is not operated by Mozilla.".

This ensures you're following the most current instructions directly from the source.

Technical guidelines

• To learn how to actually create a new article, see Create a new Knowledge Base article.
• To learn how to edit an existing article, see Edit a Knowledge Base article.
• See About the Knowledge Base for an overview of how the Knowlege Base works.
• See Improve the Knowledge Base for a full list of article documentation.

Title

• Title length: Google's search results page will display up to 60 characters. Your title can be longer than this if necessary but make sure your important keywords are included in the first 60 characters.
• Capitalization: Use sentence-case capitalization. The first word in the title should be capitalized, as well as proper nouns and names, not every major word. Use “sentence” style, not “headline” style (the same applies to heading titles). See the Style guide and copy rules section below for other rules on capitalization.
• 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 words or phrases in every title. For example, don't always start articles with “How” and avoid using “ing” task names such as “Setting the home page”.
• 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.

Slug

When you create a new article and enter a title, SUMO will automatically create a slug (the part after kb/ at the end of the URL for the article). A reviewer can edit the title of an existing article but the slug remains the same, unless manually changed (this is by design). 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.

Fix the slug

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 articles in one of the other categories, such as “How To Contribute” articles (like this one). The article's History page will show the category.

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

Keywords

The keywords field in an article can be used to improve search results on SUMO. It should be used only under specific circumstances though, as misuse can actually hurt search. We rarely need to use keywords. For details, see When and how to use keywords to improve an article's search ranking.

Write a good search summary

The article summary, along with the title, helps users judge whether 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

Number of steps

When guiding users through a process, consider ordered lists (numbered lists). It's generally a good practice to try and keep the total number of steps in the range of six-seven.

Parallel structure

Use the same phrasing or pattern of words for every step you write. Parallel structure is important in KB articles because it makes things clear and easy to follow. When similar elements have a consistent format, users can understand and complete tasks more smoothly. This structure simplifies instructions, reduces mistakes, and ensures information is conveyed effectively.

For example:

1. Find Clear history when Firefox closes. If it is selected:
   1. Click on the Settings… button.
   2. Make sure that Form & Search History is not selected.
   3. Click OK.

Directional cues

Directional cues are references or indicators that guide users to the specific location or position within a user interface where they need to take a particular action. These cues help users navigate and interact with software, applications or websites more effectively. They typically include phrases like “On the top-right corner,” “In the left-hand menu,” or “Below the search bar,” which provide users with a clear sense of where to find and perform actions.

In your KB article instructions, make sure to provide directional cues before the action. For example, instead of saying Click the button, use On the top-right corner, click the button. This format helps users easily locate and perform actions within the interface.

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: Always use terms the way they appear in the Mozilla interface. For example:

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

General computing terms:

• Website is one word. Web page is two words.
• Log in and log out are verbs. Example: “Log in to the website.” The same applies to sign in and sign out. Do not use “log into” or “sign into”.
• Login and logout are nouns (usually used as adjectives). Example: “Click the login button.”
• Use email instead of e-mail.
• The plural of CD-ROM is CD-ROMs.

Links to mozilla.org should not contain the locale:

• Use https://www.mozilla.org/ instead of https://www.mozilla.org/en-US/

When incorporating links into sentences:

• Avoid using “click here” or “here” as link text.
  • Do: Go to your account settings to cancel your subscription.
  • Don't: Click here to cancel your subscription.

Capitalize the following items:

• Proper nouns and names, including brand names, product names and feature names
• 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

Mozilla accounts:

• The “a” in Mozilla accounts is always lowercase except in navigation items where it’s included with other navigation items that are using headline casing.
• Always use “sign in” and “sign out”.
• In verb form, use “sign in to your account” (not “sign into”) to be grammatically correct.
• You can also use “Sign in with Mozilla”.
• “Sign” should always be used as a verb. If you are using it as a noun, use “login”.
• Use “sign up” as the call to action to create a new account.

For details on how to refer to Mozilla accounts in KB articles, see Editorial guidelines for Mozilla accounts.

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”.

Use initialisms that are considered to be generally understood. For example:

• HTTP
• USB
• URL

Numbers appearing in the version of a product, error codes, keys and buttons will not be spelled out.

Write instructions in active voice. Write instructions in active voice. Active voice and the present tense simplify instructions, making them easier to follow and encouraging prompt action. Example:

“Restart Firefox to update” not “Firefox has to be restarted”.

Spell out backslashes(\) and forward slashes(/) for paths and searches to avoid confusion.

Example: “Some pathnames to images contain backslashes (\\)”.

Keyboard shortcuts Capitalize the first letter of a keyboard shortcut or combination of shortcuts: Ctrl + Shift + C or Command + Shift + C.

Don't use slang and idioms. All of our articles are translated into many different languages, so they are read and translated by non-native English speakers. Slang and idioms can be ambiguous which can confuse readers and make translation more difficult.

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 macOS X (see How to use "For" tags for details).