How the Knowledge Base works
- Revision id: 13796
- Creator: michellerluna
- Comment: fixed three typos
- Reviewed: Yes
- Reviewed by: Verdi
- Is approved? Yes
- Is current revision? No
- Ready for localization: No
Like many "rules" around here, these are not set in stone. We have brand new Knowledge Base software and major Firefox releases (both desktop and mobile) coming up so things are bound to change but this should be a good overview.
Table of Contents
How our wiki is different from others
- Wiki markup
- Although we use MediaWiki markup (like Wikipedia) for most things, our wiki is designed specifically for Firefox Help and uses some custom markup for displaying instructions. See our markup chart for a list and examples.
- Review system
- Because we want to be sure that Firefox users get correct and up-to-date information, edits to our articles have to be reviewed and approved before they become live.
- We have a system for translating the English articles in our Knowledge Base into other languages. Translations are tied to their English source article and localizers are notified when it changes. For more information, see Localize Mozilla Support.
Things to consider before creating a new article
Before you run off creating new articles like a madman, let's go over some things you should consider first. These rules are not set in stone. If you have questions, you should ask them in the Articles Forum.
- What topics do we cover in the Knowledge Base?
- Using Firefox features like tabs, bookmarks and sync.
- Fixing problems like crashes or problems loading websites.
- What topics don't we cover in the Knowledge Base?
- Tricks or hacks for modifying Firefox.
- Using or recommending specific Add-ons and Plug-ins.
- Do we really need this article? – There are all kinds of things we can write about in the Knowledge Base but we want to balance how much work goes into an article (writing it, maintaining it, localizing it) with how many people it could potentially help. Our top 20 articles account for about 50% of our traffic. Often, our effort is best spent making one of those articles better. Maybe what you are thinking of documenting would work best as an addition to an existing article.
Creating a new article
If you think there's an article that we need to add to the Knowledge Base, here's how to get it done.
- Go to the Articles Forum and propose creating the article.
- Create a new thread, title it [Proposed] Name of article, and explain what the article will cover.
- Wait for comments on your proposal. This is optional but if you intend on drafting the article yourself you might want to hear what others have to say before you do it.
- Create and draft the article.
- When you've finished drafting the article, add a link to it in the article thread and change the title of the thread to [Needs Review] Name of article.
- Doing this helps to let people know that the article is waiting for review.
- The article won't be public until it's been reviewed and approved.
Improving existing articles
With nearly 300 Knowledge Base articles, there's always something that can be made better. Here are three main ways to improve an article:
- 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.
- Keep articles up-to-date – Major updates to Firefox 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 How to write Knowledge Base articles for some guidelines.