Last updated:
4 days ago
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
Purpose
As a Knowledge Base reviewer, your role is essential in maintaining the accuracy, clarity, and consistency of support content in our Knowledge Base. Your review work ensures users can trust our articles and find help easily.
Key responsibilities
As a KB reviewer, when you review a revision, always make sure that the revision:
- Is accurate and up-to-date
- Uses clear, consistent language and tone
- Is aligned with Mozilla’s editorial guidelines
- Includes correct and functioning formatting, links, and markup
- Follows accessibility and localization best practices
- Meets the scope of the article and product version
Review guidelines
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.
Review policy based on content type
Review requirements differ by content type. It’s important to review the following policy below before approving any new revision.
- New articles: All new articles must be reviewed by a CX staff member.
- Major updates: Both CX staff and contributors with KB reviewer permission can review revision with major updates. There might be exceptions where certain content may require CX staff approval, particularly for sensitive or high-impact content. In these situations, the author should indicate in the revision notes “Staff review required.”
- Minor updates: Minor updates may be reviewed by either CX staff or a contributor reviewer.
Where to find unreviewed articles
There are multiple ways you can find unreviewed articles:
- Knowledge Base Overview: This page provides you with a list of articles in order of pageview number in the past 30 days. The Status column will show which articles need review. You can also filter based on product and article type.
- Unreviewed Changes: This page provides an alternative way to see which articles need review, as well as how long each revision has been waiting to get reviewed. You can choose to sort based on pageview/most recent changes, and you can also filter based on product.
- Most Visited: This page provides you a list of Knowledge Base articles based on number of pageviews. In the Status column, you will be able to see which articles need review.
Prioritization
When reviewing multiple articles, it’s important to prioritize your efforts strategically. Consider the following:
- Article with high pageviews: Articles with a high number of views must be prioritized to ensure users are accessing the most accurate and up-to-date information. You can easily identify these by sorting the Unreviewed Changes list by view count.
- Article linked within the product: If you are part of one of the contribution groups (Forum, KB, L10n) or the “Staff” group, you may see an indicator showing that an article is linked within the product. These articles should generally take priority, as they have a direct impact on the user experience.
Special articles
- Templates include content that is reused across multiple articles and should be considered as high priority due to their broader impact. All templates, including those that need review, are listed here. For guidelines on how to use templates within articles, please refer to Using Templates.
- Canned Responses are standardized responses used in the Community Forums. Because they are reused frequently, any updates should be coordinated with the Community team. A list of all forum responses, including those that need review, is available here. For additional guidelines on creating or improving common responses, see Create or improve common forum responses.
Special requirements for subscription or premium products
Content submission
If you would like to suggest new content or propose changes, please file a Bugzilla ticket or reach out to a staff member. You can contact us either on Matrix or in the #sumo-team channel on Slack (for contributors with Slack access).
Content approval
Staff approval is required for all revisions related to Subscription or Premium products. This includes Canned Responses and Templates associated with these products.
For reference, current Subscription or Premium products include:
- Mozilla VPN
- Firefox Relay
- Mozilla Monitor
- MDN Plus
Reviewing articles
Choosing revision levels
When you approve an article, you have three different revision levels to choose from. These levels will determine the need and prioritization for localization.
- 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 major changes (updates and big changes) that don't completely invalidate the previous version of the article. Localizers won’t be notified immediately about the changes, but the revision can be marked as Ready for Localization later and it will trigger notification for the localizers.
- Major content changes that will make older translations inaccurate: This can be used when the update will cause the previous content to be outdated. Marking an article with this will trigger a warning on localized articles that the content may be out of date and provide a link to the English version for the most updated information.
Leaving 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!
Deferring a revision
If a revision is not particularly helpful, you can defer the proposed revision. Rather than being a simple rejection, however, a deferral is your opportunity to work with the revision’s author to improve their revision. You can do so by leaving a message in the comment field to thank the author and then give specific, constructive feedback about what you feel needs to change in order for the revision to be acceptable. Be sure to also include links to any relevant documentations or guidelines.
Reviewing multiple revisions
When there are multiple revisions pending for approval, make sure to check all of the revisions starting from the oldest one before making a decision. It’s important to note that 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.
Needs change
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!
How to give credit to a contributor in the KB
- To add a contributor, go to the Show History page of an article
- Scroll down under the revisions and click the “Edit contributors” link
- Type the contributor name and then click
Handling spam and mistaken edits
In the case of spam, you should simply delete the revision by clicking the trash can icon 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.
Ready for localization
How does “Ready For Localization” (RFL) work?
To prevent contributors from translating an article that is still being updated, the system only allows translation of versions that have been explicitly marked Ready for Localization (RFL). When the localizer clicks , they are given the most recent revision that has been marked as RFL.
After a new revision is approved, the article will not appear in localization dashboards as needing an update unless the Ready for Localization (RFL) flag is checked. When the RFL flag is set, the system also sends an email notification to everyone watching the article, informing them that the article is ready to be localized.
Marking an article RFL
Marking an article revision as “Ready for localization” means that we’re telling localizers the English version is done and can be translated without fear that the article will change a few more times before they're done.
Localization is a lot of work and is often done by just one person. It’s not always easy, but 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.
Marking an article RFL post-review
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.
RFL protocols
All contributor reviewers must adhere to the following localization protocols:
- All Mozilla staff and contributor reviewers may mark a net-new article or an article update as ready for localization.
- All net new articles and revisions that introduce new or changed information must be marked for localization, unless otherwise specified by Product teams based on regional availability.
- If a revision does not alter instruction, accuracy, or user experience, the localization priority must be decreased accordingly.
- In some cases, Mozilla staff may leave comment syntax or a revision comment in an article to indicate that a translation is already being submitted for internal localization in certain locales. If the comment syntax indicates that an article or revision is already being submitted for internal localization, contributors must not localize it independently.
Release readiness
To make sure that we are ready to support upcoming Firefox on-train releases, here are some guidelines regarding the timelines for release readiness. Articles that are associated with the next release are either new articles or content updates that cover functionality introduced in the next release. The following guidelines apply to articles with release-related content.
Firefox release calendar
4 weeks before the next release
- Begin planning and drafting content for the upcoming release; no work for localizers yet
- All existing articles remain open for editing and localization as usual.
1-2 weeks before the next release
- Draft content for the upcoming release may be ready internally; however, publication typically waits until the official release date to account for any last-minute changes.
- If the content requires localization prior to release, the product team must notify the CX staff so we can coordinate with the localization community to ensure deadlines are met.
Release day
- Content changes should be published in the en-US Knowledge Base. Localizers should prioritize translating articles related to the new release.
Discussion channel and escalation
Not all KB reviewers actively monitor KB Discussions. If you need to reach the entire group of KB reviewers, please email kb-reviewers@mozilla.com.
Role evaluation
Creating content that is accurate, consistent, and relevant is important, and maintaining that quality over time requires shared standard and ongoing alignment.
As a Knowledge Base reviewer, you play an important role in upholding those standards. To ensure our reviewer group stays active and aligned with current practices, the Community team conducts a light annual review based on participation and adherence to guidelines.
To retain your KB reviewer permission, we ask that you:
- Stay aligned: Adhere to the Community Participation Guidelines and the KB reviewer guidelines outlined in this article.
- Stay active: Review at least three (3) revisions within a six-month period.
If you haven’t been active or if questions arise about guidelines adherence, the Community team may reach out to you to check in before taking any action. Our goal is not to remove permissions, but to ensure reviewers feel engaged, supported, and aligned with current processes.
If circumstances change and you need to step back, we completely understand. Since this is a volunteer role, your time and availability may naturally shift. Don’t hesitate to let the Community team know when that happens. We’re always happy to reconnect when you’re ready to re-engage.
—
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!
