Learn about the Mozilla Support (SUMO) Knowledge Base and how it works.
Table of Contents
What is Knowledge Base?
The Knowledge Base is a wiki with superpowers:
- 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.
- 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.
Desktop priority
- Windows – With about 90% of our users on Windows, this is a no-brainer. For now, we should be making screenshots for Windows (preferably Windows 10) if you can only make one.
- Mac – The current version (macOS 13.0 Ventura as of October 2022)
- Linux – Use Ubuntu for screenshots.
Mobile
- Android – 4.0 + (4.0, 4.1, 4.2, 4.3, etc.).
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 forum, accessible under Editing Tools.
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 Knowledge Base discussions 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 discussions: This is the place where we discuss general topics about the KB.
- Localization discussions: This is the place where we talk about localizing SUMO.
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 archive Knowledge Base articles to keep our focus on users' most pressing items. As we periodically release updated versions of Mozilla products, the issues and items that need documentation 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 article's Description page, which can be accessed using the
option under Editing Tools. This will remove the article from all dashboards (including localization dashboards) and from the normal search. 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, you can reopen the Editing Description page and deselect the Obsolete checkbox to get the article back on the dashboards (see Edit a Knowledge Base article for details).
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 and approval guidelines.
Complete Knowledge Base guidelines
If you're really interested in editing and writing documentation, here are a few resources that should help explain how we do things:
Create new support articles
- Writing guide for Knowledge Base articles — Guide to writing techniques and styles that we use to make articles more engaging and effective. For the mechanics of actually creating or editing articles, see:
- Create a new Knowledge Base article – Steps for creating a new article, along with some sample wiki markup to get you started.
- Anatomy of a Knowledge Base article – Explains the basics of how articles are built.
- Article Description – Explains how to write description for a support article.
Improve existing support articles
- Improve the Knowledge Base – Learn how to improve SUMO Knowledge Base.
- Edit a Knowledge Base article – Steps for editing an existing article.
Other guidelines
- About the Knowledge Base — An overview of the mechanics of our Knowledge Base (You're here!)
- How to make screenshots — A step-by-step guide to creating screenshots to use in articles.
- Article review and approval guidelines – Reviewer guidelines for Knowledge Base.
- Add images and screenshots to Knowledge Base articles — Explains how to add screenshots to articles and have them display correctly.
- Markup cheat sheet – The most commonly used wiki markup in our articles.
- Markup chart — Wiki markup reference. It gives examples and shows the markup that produces them.
- How to use {for} — Special wiki markup that lets us show instructions for different application versions (for example, Firefox 115) and operating systems such as Windows and macOS.
- Using Templates — Templates are reusable pieces of content. You can include a complicated set of step-by-step instructions in multiple articles by using a template.
- When and how to use keywords to improve an article's search ranking — Explains when adding keywords to an article is appropriate.
- See more guidelines on Knowledge Base contribution here.