Article review and approval guidelines
Revision Information
- Revision id: 19770
- Created:
- Creator: Michael Verdi
- Comment:
- Reviewed: No
- Ready for localization: No
Revision Source
Revision Content
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 3000 visits/wk):
- Approve all revisions (including your own) that you believe are good and just update existing content.
- Discuss big changes in the article's forum before approving them. Don't approve your own revision if it's big change.
Other articles (less than 3000 visits/wk):
- Approve all revisions (including your own) that you believe 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.
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.
Top articles
Our top articles (more than 3000 visits per week) account for about 75% - 80% of all visits to the Knowledge Base.
- Approve all revisions (including your own) that you believe are good and just update existing content.
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.
- Discuss big changes in the article's forum before approving them. Don't approve your own revision if it's a big change.
Other articles
For articles with less than 3000 visits per week:
- Approve all revisions (including your own) that you believe improve the article.
Updating existing content
The most common task in the Knowledge Base is keeping articles up-to-date. Generally, that means making revisions to existing content. With that in mind, approve all revisions (including your own) that you believe are good and just updates existing content as follows:
- Spelling and grammar corrections
- Adding or updating screenshots
- 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
- Updating images for new versions of Firefox
- Fixing issues with wiki markup
- Fixing links
- Updating keywords
- Adding a missing search summary
Big changes
Sometimes a revision includes big changes — such as adding or removing a section. For articles with less than 3000 visits per week, approve all revisions that you believe are good and include bigger changes to the article such as:
- Adding a new section
- Removing an existing section
- Rewording, restating, simplifying existing language
- Rewriting section headings
- Reordering sections
- Changing the scope of the article
Because the 50 most visited articles articles are very popular and have been worked on extensively, bigger changes to them must be discussed in the article's forum before being approved.
Feedback for editors
For well intentioned edits to an article, a deferral is an opportunity to work with the editor or editors to take a revision that needs more work and make it ready for approval. 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, thank the editor and and give specific, constructive feedback about what you feel needs to change in order for the revision to be acceptable. Be sure to give them links to any relevant article discussions or guidelines. Writing a review when deferring an edit is generally a good practice and essential when deferring an edit submitted by a new contributor.
Spam and mistaken edits
In the case of spam, you should simply delete the revision.
In the case of mistaken submissions and misplaced help requests, 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.com/questions/new so that we can better help you.
Thanks
Once you've done that you can delete the revision.
Reviewing new articles
Unless an article is being created for a special purpose (Firefox chemspill, to be linked in-product or from mozilla.com) it should be treated like any article outside the 50 most visited. If the revision is an improvement; approve it. It's okay if the article is not 100% complete. If it's not one of those special articles it can begin to collect feedback while still being worked on.
Ready for localization
Marking an article as ready for localization is our signal to localizers that the article is currently done being worked on. Ideally, the article won't need significant changes again until a new version of Firefox or other circumstances dictate it. If all current needed changes have been addressed by the latest revision, then the article should be marked ready for localization.
Marking an article revision as "Ready for Localization" lets us tell localizers that the English version is done being worked on and it can be translated without fear that the article will change a few more times before they're done. The idea is to reduce the "notification noise" and workload for localizers. Of course, if they wish, localizers can still be notified of and follow all English article changes.
How it works:
An article is not added to localization dashboards as needing an update unless it is marked with the second or third revision levels AND the ready for localization flag is checked. This flag can currently only be checked by an admin. Doing this also sends out an email notification to everyone watching for articles that are ready to localize.
We do this for a number of reasons:
- Finalizing an article for a specific version of Firefox - For example, we can complete changes to an article for Firefox 5, mark the last revision as ready for localization and then begin making changes to the article for Firefox 6. Then, when the changes for Firefox 6 are complete, we can mark a new version of the article as ready for localization. Localizers will only be notified when the Firefox 5 article is ready and then (probably 6 weeks later) when the Firefox 6 article is ready.
- Reducing the notifications and confusion for localizers - Whether we're changing an article to reflect changes in Firefox or we're trying to improve the article, it often takes a half dozen or more revisions to an article to get everything right. Instead of localizers being alerted with each revision, we can wait until we're finished and then mark the article as ready for localization.
- Experimenting with an article - For example, we can create a radically different version of an article, try it out for a period of time and then decide whether or not to mark it as ready for localization.