Learn about the Mozilla Support (SUMO) Knowledge Base and how it works.

The Knowledge Base is a wiki with super powers

• Special wiki markup - Although we use MediaWiki markup (like Wikipedia) for most things, our wiki is designed specifically for Mozilla Support and uses some custom markup (called {for}) so that we can show one set of instructions to Windows users, for example, and another to Mac users.
• Review system - Because we want to be sure that people get correct and up-to-date information, edits to our articles have to be reviewed and approved before they become live.
• Translations - Most of our users speak a language other than English. We have a whole system for translating the English articles in our Knowledge Base into other languages.

Audience & scope of the Knowledge Base

Since Mozilla products are used by millions of people at all skill levels, the Knowledge Base should be written for a general audience rather than one very familiar with computer techniques and terminology. We mainly cover features (like tabs, bookmarks and sync) and fixing problems (like crashes or problems loading websites). We don't cover every feature, setting or problem. Instead we look at what users tell us (in article discussions, support forums, article views) and use our experience and judgment to decide exactly what to cover.

What topics don't we cover in the Knowledge Base?

• Tricks or hacks for modifying a product
• Developer and advanced features like the error console or web console

Organizing our work

How do we prioritize what we work on?

We mainly work on articles in order of their popularity. This generally represents our users' priorities. Currently the top 20 articles account for over half of all views. Making our top article more helpful can potentially help as many people as improving the bottom 100 articles. We keep track of changes that need to be done in this dashboard. It's sorted by article rank so that you can easily see what should be worked on first.

Exceptions:
Of course popularity isn't the only priority. These exceptions also need to be taken into account.

• Breaking issues - Occasionally, new issues are reported in our support forum that are best dealt with by updating a Knowledge Base article. For example, a problem that affects people using the Flash plugin (most Firefox users) would be more important to update than a minor change to an existing feature in an upcoming version of Firefox.
• Anticipated demand - Occasionally we'll update an article in anticipation of a new feature or feature change. The current article may not have a particularly high rank but we're reasonably sure based on experience and marketing plans that these articles will become popular.
• Mobile documentation - Because Mozilla products for mobile devices such as Firefox for Android and Firefox for iOS have comparatively few users, their articles can't be expected to "compete" with desktop Firefox articles. The articles for these products should be considered in the context of the relative demand for documentation of features and issues related to the individual product.
• Linked articles - These are articles linked from inside products or mozilla.org.

Where do we talk about articles?

We generally have two types of conversations about knowledge base articles:

• Individual articles - each article has its own discussion tab. Registered users can post feedback about the articles here, and we can discuss what revisions the article needs, the relative merits of revisions and issues related to the article.
  
• The Knowledge Base as a whole - we discuss ideas and issues with the overall KB strategy, policies and software in the Articles Forum.

How do I keep up with what's going on?

• Mozilla Support (SUMO) blog: The latest project updates and developments are discussed here.
• Contributor News & Resources: This is another good source of information - it's updated every week or so.
• SUMO community discussions: This is where contributors talk to one another.
• KB Articles forum: This is the place where we discuss general topics about the KB.
• Localization Forum: This is the place where we talk about localizing SUMO.

Improving articles

Improving Knowledge Base articles is probably 90% of the work that we do. There's always something that can be made better. Here are three main ways to improve an article:

• Keep articles up-to-date – Major updates to Mozilla's products and services always bring new features and changes to how existing ones work. It's always best when our instructions actually match how things work in the product.
• Proof-read – Some of you have special powers to spot the mistakes that spell-check misses (how many have you noticed in this article so far?). We need your help.
  • Correct spelling, grammar and punctuation.
  • Fix issues with style and formatting. See Writing guide for Knowledge Base articles, How to use "For" tags and Using Templates for some guidelines.
• Make articles easier to understand
  • Find a better way to explain something that is too complex or not very clear.
  • Add screenshots to help people understand what in the world the article is referring to. Most people probably don't know the difference between the location bar, search bar or any other bar unless it has a happy hour.
  • Add screencasts. This is the next best thing to actually grabbing the mouse out of someone's hand and doing it for them.

What is the process for editing an article?

At a minimum, all you have to do is click Edit Article, make some changes and submit it for review. The full process looks like this:

1. Go to the Need Changes section of the Contributor Dashboard
2. From comments that describe what needs to be done, choose an article. Expand Editing Tools and take a look at the discussion in order to have information pertinent to this article.
3. Edit the article. See How to write knowledge base articles for style tips.
   • Use the Preview Content button to check your changes.
4. Click the Submit for Review button to save your changes. Your edit will be listed in the Unreviewed Changes section of the Contributor Dashboard.

If it's taking a long time to get a review, you can ping @jsavage:mozilla.org in the SUMO Matrix room or via email.

If the reviewer doesn't approve the article, they will post their reasons and feedback in the Discussion page thread for the article. Sometimes, they will also create a new revision based on yours and add or change things.

You (or anyone else) can create another revision and make more changes. It generally takes a few rounds to get things right.

Creating a new article

If you think there's an article that we need to add to the Knowledge Base, here's how to get it done.

1. Create a new article and fill out the form using the source for another article as a guide.
2. Draft the article content.
3. Check your work using the Preview Content button.
4. Click the Submit for Review button and include the reason for drafting the article in the comment.
   • Doing this gets the article on the KB Dashboard to let people know that the article is waiting for editing or review.
   • The article won't be public until it's been reviewed and approved.

Style

We want Mozilla Help to be usable by all users. This means we're writing for a general audience rather than one very familiar with computer techniques and terminology.

• The person you're writing for doesn't know how to change preferences or add a toolbar button without step-by-step instructions.
• Assume that people haven't changed any of the default product or operating system settings.
• Conversational writing style – Use an informal, active style similar to the way you'd speak to someone in person.
• 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.

For more information, see Writing guide for Knowledge Base articles.

Markup

Our wiki uses MediaWiki syntax along with a few special things for styling buttons, keys, menus, etc. See the Markup chart for a list and examples.

{for}

How to use "For" tags contains instructions and examples for showing and hiding instructions for different Firefox versions and operating systems.

Templates

We have a list of templates that we use in articles so that the same bit of instruction doesn't have to be re-written, localized and kept in sync across multiple articles. Using Templates explains how it works.

Screenshots & Screencasts

We should make sure that articles are written to work without images or videos. Though both images and videos are important and greatly increase the helpfulness of an article, they can’t be mandatory. Localizers should feel free to use or delete them as they see fit.

Desktop Priority

1. Windows - with about 90% of our users on Windows this is a no-brainer. For now we should be making screenshots of Windows 7 or above if you can only make one.
2. Mac - the current version is macOS 10.14 (Mojave).
3. Linux - use Ubuntu for screenshots.

Mobile

• Android - 4.0 + (4.0, 4.1, 4.2, 4.3, etc.).

Adding and removing articles

Proposing new articles

Our knowledge base is what makes our entire support effort scale to serve hundreds of millions of Firefox users. The most efficient thing we can do is answer people's questions about Mozilla's products and services with an article. But articles don't come without a cost. Each one has to be written, localized and maintained. With many features and issues already documented it's often a better use of our collective time to make existing articles better. Before you start creating new articles, let's go over some things you should consider first:

Do we really need this article?
These are the main reasons why we add a new article to the Knowledge Base though it often makes more sense to update or add to an existing article.

• New features - User facing features that are likely to generate a lot of interest and questions from users. This may be an inherent aspect of the feature, a result of marketing and in-product links or a combination of the two.
• New issues - Issues that have many recent threads and votes in the support forum.
• High impact - Critical, time-sensitive issues that need temporary documentation (e.g., Firefox startup crash with G DATA security software).

Archiving articles

We'll periodically archive knowledge base articles to keep our focus on users' most pressing items. As we release Mozilla's products every six weeks the issues and items that users will need documentation for will change at a much faster rate. There will be a lot of articles (like Bookmarks in Firefox or How to set the home page) that will stay around for a long time, but there will be others that become obsolete or not of concern for users.

How it works:
Contributors with reviewer privileges can mark an article as obsolete by editing the description section of an article. This will remove the article from all dashboards (including localization dashboards) and from the normal search. You can still see the article by using the advanced search, and, of course, links to the article would be preserved. However, there will be a banner on top of the article making it clear that the article is no longer maintained and might be out of date.

Archiving an article is not a one-way street. Once an article is archived, we will monitor the stats to make sure that the article wasn't a popular one. If we've made a mistake, it's as easy as clicking a checkbox to get the article back on the dashboards.

Factors to consider before archiving an article:

• Low views - Generally, articles with less than about 1500 visits/month.
• Few recent reports - Issues that have relatively few recent threads and votes in the support forum.
• Low impact - Removal of the article is not likely to cause or exacerbate a serious issue.
• Changes to products and services - Instances where an issue has been fixed or a change in the behavior has made something obsolete.

Article review guidelines

To learn about guidelines for reviewing Knowledge Base articles, see Article review guidelines.