Last updated:
Our Knowledge Base reviewers are Mozilla contributors and staff with experience and skill in writing support documentation. Here are some guidelines for reviewing articles.
Table of Contents
Reviewing articles
Most revisions are made by people volunteering their time and talent. When dealing with the work that people have submitted, assume that everyone has the best intentions and be sure to thank them for their contribution. Remember, you may be the first and only contact that person has with someone from Mozilla. Please make it positive.
The Knowledge Base Dashboard Overview lists articles in order of visits in the past 30 days. The Status column will show which articles need review. All revisions should be reviewed in a timely manner, not just the top articles.
The Unreviewed Changes list is an alternative way to see which articles need review, as well as which revisions have been pending review for the longest period of time. (If you select a specific product from the drop-down list, you can sort the list by “Most Recent”.)
Top articles
Our top articles with more than 100,000 visits per month (of which are about 20 articles for Desktop) account for about 50-55% of all visits to the Knowledge Base. Our top Android articles are those with more than 5,000 visits per month.
It's critical that these articles have the latest information.
Because the top articles have been edited extensively and affect a large number of people, big changes to the article should be discussed first. Feel free to private message other Knowledge Base contributors to ask them chime in. It's best if a consensus can be reached but that is sometimes difficult to pin down. As always, use your best judgement.
- For big changes — Don't approve your own revision if it's a big change. Please follow the article approval guidelines below. If needed, please start a discussion in the article discussion thread.
Other articles
Articles with less than 100,000 visits per month for Desktop (or those with less than 5,000 visits for Android) represent the vast majority of our Knowledge Base (about 600+ articles; 45-50% of visits). They cover less common issues and newer products. Please follow the article approval guidelines below.
New articles
When we're first creating an article, it doesn't have any visits at all. So how do you treat it?
- If the article is being created for a special purpose (Firefox chemspill release, to be linked from a product or from mozilla.org), or is a canned response, treat it as one of the top articles.
- If we don't have any reason to think the article will be super popular right away, treat it like the other articles with less than 100,000 Desktop or 5,000 Android visits/month. If the revision is an improvement, approve it. It's okay if the article is not 100% complete. If it's not one of the top articles it can begin to collect feedback while still being worked on.
- Once a new article has been approved but has been out for less than a month consider looking at the 7 day view.
Special articles
- Templates include content used in multiple articles and should be considered as top articles. All templates, including those that need review, are listed here. See Using Templates for additional guidelines.
- Canned Responses are rather more important in the support forum than viewing numbers suggest. Treat new forum responses, or anything more than a minor correction or clarification, as a big change. All forum responses, including those that need review, are listed on this page. See Create or improve common forum responses for additional guidelines.
Article review and approval guidelines
Creating top-notch content on SUMO plays a crucial role in building trust with our users and establishing our credibility. To ensure that all content meets high standards of quality, accuracy, and consistency, we have implemented a review requirement for all KB content, regardless of the author.
Whenever a revision is made to KB content, it must undergo at least one round of review. This review can be conducted either by a staff member or a peer contributor, depending on the specific product. Even content created by our staff members needs to go through this review process, although the approval itself may take place outside of SUMO for staff members.
For further clarification, we have provided information below regarding which products require staff approval exclusively and which ones can be approved by co-contributors.
By adhering to these review and approval practices, we can ensure that the content on SUMO maintains a high level of quality and accuracy, providing our users with reliable and valuable information.
Staff review guidelines
All products
All internal staff members are required to have their en-US content reviewed by at least one other party. Examples of content reviewers may include product support managers, product managers, legal, marketing, PR, or community contributors.
Content reviews can take place within SUMO or within a Google Doc. If your content went through a review outside of SUMO, simply add a note in your SUMO revision, mentioning the team or individuals who gave it a thumbs up. See an example below.
Content contributor review guidelines
Free products
Please do not self-approve your own revisions (en-US only). Please ask other contributors or staff members to review them, instead.
Recent revisions for en-US and Unreviewed changes will be reviewed at least three times per week by staff and reviewers. Pending revisions should be approved or deferred without needing to be contacted. If there isn't a critical reason for immediate approval, a reasonable amount of time (seven days or more) should pass before an editor should contact staff or another reviewer, if staff approval is not needed.
There may be exceptions where certain content requires staff review and approval. In these situations, the author will indicate in the revision notes that “Staff review required.” If you happen to propose a revision to one of these articles, please be sure to flag it for a staff writer's attention (via SUMO direct message or Slack), so they can provide the necessary review and approval.
By working together and involving others in the review and approval process, we can maintain the highest standards of quality and ensure that our content is top-notch. Thank you for your cooperation, and let's continue to create amazing revisions for our users!
Review requirements matrix
| Product | En-US self-approval | En-US co-contributor approval | En-US staff-only approval |
| Firefox desktop | No | Yes | No* |
| Firefox for Android/iOS | No | Yes | No* |
| Focus Android/iOS | No | Yes | No* |
| Thunderbird | No | Yes | No* |
| Firefox for Enterprise | No | Yes | No* |
| Mozilla Account | No | No | Yes |
* Unless indicated by the author as “Staff approval required” in revision notes.
Articles with special requirements
| Article | En-US self-approval | En-US co-contributor approval | En-US staff-only approval |
| How to customize Firefox Suggest settings | No | No | Yes |
Subscription/Premium products
Please don’t self-approve your revisions or approve revisions from other contributors (en-US only). This includes Canned Responses and Templates for subscription/premium products. If you propose a revision, please flag it to a staff writer for approval (via SUMO direct message/private message, Matrix or Slack).
By working together and ensuring that staff writers are involved in the approval process for premium product content, we can continue making our content the best it can be for our customers.
Review requirements matrix
| Product | Self-approval | Co-contributor approval | Staff-only approval |
| Mozilla VPN | No | No | Yes |
| Firefox Relay | No | No | Yes |
| Monitor | No | No | Yes |
| No | No | Yes | |
| MDN Plus | No | No | Yes |
| Hubs | No | No | Yes |
Review guidelines compliance
Creating content that is consistent, accurate, and relevant is important, but it's not the only step in the process. To make sure our content maintains its quality over time, we need everyone involved to understand and follow the review and approval processes. Our staff will be keeping an eye on how well we're following the new guidelines to make sure everything stays on track.
To retain your Knowledge Base Reviewer permission as a contributor:
- Adhere to the above review guidelines.
- Adhere to the Community Participation Guidelines.
We also strongly encourage all Knowledge Base Reviewers to review at least three (3) article revisions per month.
Your Knowledge Base Reviewer permission as a reviewer may be revoked if you self-approve en-US content. Please see guidelines below:
- 1st violation: A private, written warning from SUMO staff, with clarity of violation and consequences of continued behavior.
- 2nd violation: A second private, written warning from SUMO staff, with clarity of violation and consequences of continued behavior.
- 3rd violation: A private, written message and your permission as a reviewer will be revoked. If you wish to regain the permission, you are required to wait at least six (6) months before requesting.
By embracing this approach, we encourage teamwork, ensure the best possible content, and create an environment where everyone's expertise contributes to our success.
What's an update to existing content?
The most common task in the Knowledge Base is keeping articles up-to-date. Generally, this covers:
- Spelling and grammar corrections
- Simplifying existing language, removing jargon
- Updating or adding screenshots
- Updating or adding screencasts
- Removing content for Firefox versions we no longer support
- Updating step-by-step instructions to support new versions of Firefox
- Updating existing text to support changes in new versions of Firefox
- Fixing issues with wiki markup
- Fixing links
- Updating keywords
- Adding or updating a search summary
What's a big change?
Big changes are ones that fundamentally change the existing article. They include:
- Adding a new section
- Removing an existing section
- Extensive rewriting (more than simplifying and removing jargon)
- Rewriting section headings
- Reordering sections
- Changing the scope of the article
Revision levels
When you approve an article, you have three different revision levels to choose from:
- Minor details that don't affect the instructions: These are changes that won't change instructions to users. Localizers won't be notified about these changes.
- Content changes that don't require immediate translation: This is the default choice. These are significant changes (updates and big changes) that don't completely invalidate the previous version of the article.
- Major content changes that will make older translations inaccurate: This is for the rare case that an article is so wrong that without these changes it will cause major problems for people. This will add a warning on localized articles that the content may be out of date and provide a link to the English version.
Feedback for editors
When approving an article, it's important to thank the editors for their contribution. It's also nice if you can give them feedback. Has their writing improved? Did they do an especially good job explaining something complex? Let them know!
If a revision contains more than just a simple mistake, is a big change to a top article that hasn't been discussed, or is something you don't feel is helpful, you should defer approval. Rather than being a simple rejection, however, a deferral is your opportunity to work with the editor to make that revision ready for approval. So, please thank the editor and then give specific, constructive feedback about what you feel needs to change in order for the revision to be acceptable. In addition to the comment field when deferring a revision, you can also add a thread to the article Discussion forum with more detailed information and refer the editor to the article Discussion forum. Be sure to give him/her links to any relevant article discussions or guidelines.
Reviewing multiple revisions
Approving the latest revision doesn't mean you're approving the earlier revisions that are pending for review. When there are multiple revisions pending for approval, make sure to check all of the revisions before making decision to approve one. You can't review older revisions when a newer revision has been approved. You will see that they are still pending for approval, but it won't be possible to review them.
Ready for localization
Marking an article revision as “Ready for Localization” lets us tell localizers that the English version is done and can be translated without fear that the article will change a few more times before they're done.
When you are approving a revision, if all of the changes needed (needs change notes, article discussion forum) have been done and more are not planned (for the current or next release), mark the article as ready for localization.
Localization is a lot of work and is often done by just one person. Only the top 20 or so articles get localized in some locales. Our top articles generally don't need any changes, other than updates for a new version of Firefox. Since we know what's coming, we try to make sure that all required changes are done before a Firefox release so that localizers can use that extra time for getting their work done.
If you are not marking a revision as ready for localization when approving it (like in the case above), you can mark it ready at any time by clicking the “Not ready for localization” status entry (an X symbol) under the R column of the article revision history and confirming.
Revisions that have been marked RFL have a checkmark symbol.
How does “Ready For Localization” (RFL) work?
In order to prevent someone from translating an article in flux, when you click “Translate article”, you are given the most recent version that has been marked ready for localization. Once a new revision of an article has been approved, the article is not added to localization dashboards as needing an update unless the revision is marked with the second or third revision levels AND the ready for localization flag is checked. This also sends out an email notification to everyone watching for articles that are ready to localize.
Next release content
Articles with next release content are either new articles or content changes to existing articles, that cover functionality introduced in the next release. The following guidelines apply to articles with release-related content:
Release-based KB Editing Timeline
4 weeks before next release
- Planning and drafting content for the next release; no work for localizers for the next release yet
- All existing content is open for editing and localization as usual; please focus on localizing the most recent/popular content
3 weeks before next release
- Next release content is finished by end of this week; no work for localizers for the next release yet
- All existing content is open for editing and localization as usual; please focus on localizing the most recent/popular content
1-2 weeks before next release
- Next release content changes have been made in en-US/English, and localizers should focus on translating this content
- All other existing content is deprioritized, but can be edited and localized as usual
Needs changes
When approving a revision, you have to decide what, if anything, still needs to be changed. If everything specified in the “Needs change comment” has been taken care of, you can uncheck it (clearing the comment) and approve the article. If there are still things that need to be done, make sure the checkbox is checked and update the comment. This way, we can easily keep track of what work needs to be done on articles.
Giving credit
Sometimes people that participate in a discussion about an article make significant contributions to a revision even if they weren't the one to actually edit the wiki. In cases like this, you can edit the list of contributors to an article (on the article history page) to include them. Bonus points for letting them know you did this!
To add a contributor, go to the Show History page for an article. Scroll down under the revisions and click the “Edit contributors” link, type the contributor name and then click .
Spam and mistaken edits
In the case of spam, you should simply delete the revision by clicking the “trash can” symbol in the article revision history and confirming. In the case of mistaken submissions (no changes) and misplaced help requests (the edit is basically a support question), you should defer and include this message in your comments:
Hi.
It appears you may have been trying to get help with Firefox. If that is the case, please ask your question again here, https://support.mozilla.org/questions/new so that we can better help you.
Sorry for the inconvenience.
Once you've done that, you can delete the revision.
