Article review guidelines
Table of Contents
- 1 Reviewing articles
- 2 What's an update to existing content?
- 3 What's a big change?
- 4 Revision levels
- 5 Feedback for editors
- 6 Ready for localization
- 7 Needs changes
- 8 Giving credit
- 9 Spam and mistaken edits
Our Knowledge Base reviewers are Mozilla contributors and staff with experience and skill in writing support documentation. Here are some guidelines for 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).
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.
- For updates to existing content — you can approve all revisions (including your own) that you think improve the article.
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.
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.
- 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
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 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 currently planned, go ahead and mark the article as ready for localization.
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 not mark the top articles as ready for localization within the four-week period before a new release. (You can find a release schedule here.) 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, 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.
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.
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.
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!
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, 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.