Improve the Knowledge Base
Revision Information
- Revision id: 241139
- Created:
- Creator: Kiki
- Comment: updated link to renamed article
- Reviewed: No
- Ready for localization: No
Revision Source
Revision Content
Improving articles
The most common thing we do in the glamorous world of Knowledge Base maintenance is to try to improve the articles we already have. Here are three main ways to improve an article:
- Keep articles up-to-date – Major updates to Mozilla's products and services always bring new features and changes to how existing ones work. It's always best when our instructions actually match how things work in the product.
- Proof-read – Some of you have special powers to spot the mistakes that spell-check misses (how many have you noticed in this article so far?). We need your help.
- Correct spelling, grammar and punctuation.
- Fix issues with style and formatting. See Writing guide for Knowledge Base articles, How to use "For" tags and Using Templates for some guidelines.
- Make articles easier to understand
- Find a better way to explain something that is too complex or not very clear.
- Add screenshots to help people understand what in the world the article is referring to. Most people probably don't know the difference between the location bar, search bar or any other bar unless it has a happy hour.
- Add screencasts. This is the next best thing to actually grabbing the mouse out of someone's hand and doing it for them.
Where to look for an article needs updating
- Need Changes list: This list can be sorted by product. Clicking on a link will open the article's History page. From there, click Article under Editing Tools to view the article, click Edit Article to update the article or click Discussion to discuss needed changes.
- Knowledge Base Overview: This list can be sorted by product and category. It includes a "Status" column for pending reviews and a "Needs Update" column for needed changes.</div>
What is the process for editing an article?
See Edit a Knowledge Base article for a guide to editing articles. At a minimum, all you have to do is click , make some changes and submit it for review. The full process looks like this:
- Go to the Knowledge Base Dashboard and click on the title of an article that needs an update.
- Take a look at any recent Discussion and check the article History (both are linked under ) in order to have information pertinent to this article.
- Edit the article. See How to write knowledge base articles for style tips.
- Use the button to check your changes.
- Click the button to save your changes. Your edit will be listed in the Knowledge Base Dashboard.
If a reviewer defers your revision, they will post their reasons and feedback in the Discussion page thread for the article. Sometimes, they will also create a new revision based on yours and add or change things.
You (or anyone else) can create another revision and make more changes. It generally takes a few rounds to get things right.
Complete Knowledge Base Guidelines
If you're really interested in editing and writing documentation, here are a few resources that should help explain how we do things:
Create new support articles
- Writing guide for Knowledge Base articles — Guide to writing techniques and styles that we use to make articles more engaging and effective. For the mechanics of actually creating or editing articles, see:
- Create a new Knowledge Base article – Steps for creating a new article along with some sample wiki markup to get you started
- Anatomy of a Knowledge Base article – Explains the basics of how articles are built
- Article Description - Explains how to write description for a support article
Improve existing support articles
- Improve the Knowledge Base - Learn how to improve SUMO Knowledge Base (You're here!)
- Edit a Knowledge Base article - Steps for editing an existing article
Other guidelines
- About the Knowledge Base — An overview of the mechanics of our Knowledge Base
- Article review and approval guidelines - Reviewer guidelines for Knowledge Base
- How to make screenshots — A step-by-step guide to creating screenshots to use in articles
- Add images and screenshots to Knowledge Base articles — Explains how to add screenshots to articles
- Add images and screenshots to Knowledge Base articles — Explains how to get screenshots and other images to display correctly in articles
- Markup cheat sheet – The most commonly used wiki markup in our articles
- Markup chart — Wiki markup reference. It gives examples and shows the markup that produces them
- How to use {for} — Special wiki markup that lets us show instructions for different application versions (for example, Firefox 40) and operating systems such as Windows and Mac OS
- Using Templates — Templates are reusable pieces of content. You can include a complicated set of step-by-step instructions in multiple articles by using a template.
- When and how to use keywords to improve an article's search ranking — Explains when adding keywords to an article is appropriate
- To see more guidelines on Knowledge Base contribution, click here