Article review guidelines

Our Knowledge Base reviewers are Mozilla contributors and staff with experience and skill in writing support documentation. Here are some guidelines for reviewing articles.

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 to be reviewed. All revisions should be reviewed in a timely manner, not just the top articles. The Unreviewed Changes list is an alternative way to see what articles need to be reviewed and which revisions have been pending review for the longest period of time (you can sort the list by "Most Recent" and work from the bottom).

Top articles

Our top articles (more than 100,000 visits per month, 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 β€” please discuss them in the article's forum before approving them. Don't approve your own revision if it's a big change. (If you have had a discussion open for at least 36 hours with no objections you may then self approve, if you are happy with your own work.)

The 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. Here the review policy is more lenient.

  • Approve all updates and big changes (including your own) that you think improve the article.
Note: Just because you can approve your own revision doesn't mean you have to. There is nothing wrong with asking another reviewer to take a look at your work.

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, 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

  • Canned Responses are rather more important in the support forum than viewing numbers suggest. Treat new articles or anything more than a minor correction or clarification as a big change. See Create or improve common forum responses for additional guidelines.

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.

    Revision Level

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!

Note: If a revision is good but contains a minor mistake (typo, markup mistake, etc.), just approve it and then make and approve a new revision that fixes the mistake.

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


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, go ahead and mark the article as ready for localization.

Ready for L10n
Note: Articles with approved content changes that have not been marked ready for localization are listed in the Changes Not Ready for Localization page.

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.

Note: Remember that, if you use the first/minor revision level, there is no option to mark the article as ready for localization because localizers don't get notified of changes with this revision level.

If you are not marking a revision as ready for localization when approving it (like in the case above), you can mark it ready by clicking the status on the revision's history entry and confirming.

Ready for localization 2

How does "Ready For Localization" (RFL) work?

In order to prevent someone 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 (codename: RocKET)

Note: You can find a release schedule for Firefox here.

6 weeks before next release / release week for current release

  • No work on next release content for English; minor fixes for existing English content; please avoid setting edited articles to RFL unless it’s critical (consult Joni or another admin).
  • Localizers finish content localization and fix potential last-minute issues with release content - this has priority over other existing content (= non-current-release), that can be localized as usual

5 weeks before next release / 1 week after current release

  • No work on next release content for KB editors or localizers
  • All existing content is open for editing and localization as usual; please focus on localizing the most recent / popular content

4 weeks before next release / 2 weeks after current release

  • Joni starts 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 / 3 weeks after current release

  • Joni finishes working on next release content 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

2 weeks before next release / 4 weeks after current release

  • Only Joni or other admins can introduce and/or approve potential last minute changes of next release content; only Joni or other admins can set new content to RFL; localizers should focus on this content
  • All other existing content is deprioritized, but can be edited and localized as usual

1 week before next release / 5 weeks after current release

  • Only Joni or other admins can introduce and/or approve potential last minute changes of next release content; only Joni or other admins can set new content to RFL; localizers should focus on 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 need to be done on articles.

Changes Needed

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!

Add Contributors

Spam and mistaken edits

In the case of spam, you should simply delete the revision (click the "X" in its entry in the history view). 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:
It appears you may have been trying to get help with Firefox. If that is the case, please ask your question again here, so that we can better help you.
Sorry for the inconvenience.

Once you've done that you can delete the revision.

Delete Spam

Note: You cannot delete an unapproved article that is spam or a support request by deleting its revisions. Refer these articles to an admin.

Was this article helpful? Please wait...

These fine people helped write this article: AliceWyman, Verdi, scoobidiver, John99, rabbihossain, jsavage, vesper, Laucon. You can help too - find out how.