Article review guidelines | How to contribute

Article review guidelines

Our Knowledge Base reviewers are Mozilla contributors and staff with experience and skill in writing support documentation. Like the title says, this article covers guidelines for reviewing articles. Here's the short version (mind numbing details are below the table of contents):

Top articles (more than 64,000 visits/month):

  • For updates to existing content — you can approve all revisions (including your own) that you think improve the article.
  • 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.

Other articles (less than 64,000 visits/month):

  • Approve all updates and big changes (including your own) that you think improve the article.

Feedback for editors:
When reviewing, be sure to include a message to the editor thanking them for their contribution. If you defer a revision, you should also give specific, constructive feedback about what you feel needs to change in order for the revision to be acceptable.

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.

Top articles

Our top articles (more than 64,000 visits per month; about 20 articles) account for about 50-55% of all visits to the Knowledge Base. 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.

The articles with less than 64,000 visits per month represent the vast majority of our Knowledge Base (about 200+ 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 mozilla.org), 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 64,000 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.

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 even if you mark them "Ready for localization."
  • 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.

Approve

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. But rather than being a simple rejection, 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. Be sure to give him/her links to any relevant article discussions or guidelines.
Defer

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

Top article "freeze"

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 four weeks prior to a Firefox release so that localizers can use those four weeks for getting their work done.

Therefore, we should only mark top articles as ready for localization four weeks before a release. All updates for the next six weeks should NOT be marked ready for localization. Of course if there is a change that is critical and should be translated, we'll have to make an exception. Also, remember that if you use the first/minor revision level, you CAN mark the article 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 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. And 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.

Hot Topics

We have a special topic called "Hot Topics." These are prominently listed on the product start pages. Generally we want to display no more than 3 - 5 articles in this list. These are determined on a case-by-case basis taking into consideration how widespread the issue is, how severe and sometimes how timely. We discuss these in our weekly meeting. As a rule of thumb, we'll leave an article on the hot topic list for a week after it's no longer really a big issue to allow time for people to see it.

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

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.



Share this article: http://mzl.la/Ha85gm

Was this article helpful?

Please wait...

These fine people helped write this article: AliceWyman, Verdi, scoobidiver, rabbihossain. You can help too - find out how.
Get support for another platform:
Customize this article

Firefox

Firefox for Android

Firefox OS