About the Knowledge Base

Revision Information
  • Revision id: 15231
  • Created:
  • Creator: Michael Verdi
  • Comment: Saving work in progress
  • Reviewed: No
  • Ready for localization: No
Revision Source
Revision Content

New intro/overview

  • 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.
  • Translations
    • 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 How to contribute to article localization.

Who are we writing for?

Audience

Scope

The knowledge base is written for a general audience and covers features (like tabs, bookmarks and sync) and fixing problems (like crashes or problems loading websites). We don't cover every feature, setting or problem. Instead we look at what users tell us (article discussion tab, support forums, live chat, article views) and use our experience and judgement to decide exactly what to cover.

What topics don't we cover in the Knowledge Base?

  • Tricks or hacks for modifying Firefox.
    • Troubleshooting articles are often an exception to this rules. If a common problem can only be fixed with a "hack", we'll document that.
  • Developer and advanced features like the error console or web console.

Organizing our work

Priorities

Work on articles in order of their popularity. This generally represents our users' priorities. Currently the top 25 articles account for over half of all views. Making our top article more helpful can potentially help as many people as improving the bottom 100 articles. The Article Tracking page can be sorted by article rank so that you can easily see what should be worked on first. Exceptions:
Of course popularity isn't the only priority. These exceptions also need to be taken into account.

  • Anticipated demand - Occasionally we'll update an article in anticipation of a new feature or feature change. The current article may not have a particularly high rank but we're reasonably sure based on experience and marketing plans that these articles will become popular.
  • Breaking issues - Occasionally, new issues are reported in our support forum and/or live chat that are best dealt with by updating a knowledge base article.
  • Mobile, Sync and Firefox Home documentation - Because these products have comparatively few users, their articles can't be expected to "compete" with desktop Firefox articles. The articles for these products should be considered in the context of the relative demand for documentation of features and issues related to the individual product.
  • Linked articles - These are articles linked from inside products or mozilla.com.

Discussions about articles

We generally have two types of conversations about knowledge base articles:

  • Individual articles - each article has its own discussion tab. Registered users can post feedback about the articles here and we can discuss what revisions the article needs, the relative merits of revisions and issues related to the article. Previously we used the Articles Forum for this purpose so there is a lot of historical information on articles there.
  • The knowledge base as a whole - we can now discuss ideas and issues with the overall kb strategy, policies and software in the Articles Forum instead of the Community Forum.

Discussions

We generally have two types of conversations about knowledge base articles:

  • Individual articles - each article has its own discussion tab. Registered users can post feedback about the articles here and we can discuss what revisions the article needs, the relative merits of revisions and issues related to the article. Previously we used the Articles Forum for this purpose so there is a lot of historical information on articles there.
  • The knowledge base as a whole - we can now discuss ideas and issues with the overall kb strategy, policies and software in the Articles Forum instead of the Community Forum.

Improving articles

With about 200 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.

Editing

This process is for things bigger than spelling & grammar fixes

  1. Go to the Article Tracking, click the rank sort button and look for articles with the status of "Needs Updates"
  2. If it hasn't been created already, in the article's discussion tab, create a new thread titled, "[Needs Update] Reason for change" and explain what needs to be changed and let everyone know that you will work on it.
    • Bonus points for editing the article's entry on the Article Tracking page to say "In Progress"
  3. After editing the article, post back in the same thread with a summary of what you did and ask for someone to review it.
  4. If the reviewer doesn't approve the article they should reject it and post their reasons and feedback in the thread.
  5. The editor (or the reviewer) can then either create a completely new revision or base a new revision off of the rejected one and make the suggested changes.
  6. When the reviewer approves the article they should post back in the thread stating that they approved it.
    • Bonus points for changing the thread topic to "[Approved] and updating the Article Tracking page status to "Updated".

Style

We want Firefox Help to be usable by all Firefox users. This means we're writing for a general audience rather than one very familiar with computer techniques and terminology.

  • The person you're writing for doesn't know how to change preferences or add a toolbar button without step-by-step instructions.
  • Assume that people haven't changed any of the default Firefox or operating system settings.
  • Conversational writing style – Use an informal, active style similar to the way you'd speak to someone in person.
  • Images and video – Using images and video to explain things along with text is not only the next best thing to being there to help in person, they are an easy way of including multiple learning styles and repetition.

For more see, How to write Knowledge Base articles

Markup

Explanation + link

Explanation + link

Templates

Explanation + link

Screenshots & Screencasts

We should make sure that articles are written to work without images or videos. Though both images and videos are important and greatly increase the helpfulness of an article, they can’t be mandatory. Localizers should feel free to use or delete them as they see fit.

Desktop Priority

  1. Windows - with about 90% of our users on Windows this is a no-brainer. For now we should be making screenshots of Windows 7. When we add support for Windows XP, we'll want to add specific screenshots for it.
  2. Mac - Current version is 10.6 (Snow Leopard). 10.7 (Lion) comes out next month.
  3. Linux - use Ubuntu for screenshots.

Mobile

  1. Android - 2.2 Froyo. Eventually we'll want to switch to the 2.3 Gingerbread look included in Firefox 5 (same look on 2.2) as more devices get the update.

For reviewers

Reviewing

  • Don't approve your own edits unless they are minor (e.g. spelling and grammar changes, updating an image, etc.). At the very least get someone to check your spelling, grammar and wiki markup.
  • Pick the appropriate revision level.
    • Minor details like punctuation and spelling errors - this is the first (default) level. The idea here is that these are changes that are inconsequential to localizers. They will not be notified of this change and it will make no difference to their version of the article.
    • Content changes that don't require immediate translation - the second level. Choosing this will notify localizers and the article will show up on dashboards and needing to be updated. This is what you'd use for most changes - updating an image, fixing markup, adding or removing important (but not critical) sections.
    • Major content changes that will make older translations inaccurate - the third level. This will notify localizers and the article will show up on dashboards as being out of date. Also a yellow warning will be places at the top of the article telling users that the English version has the most accurate information. This would be used in cases where the old instructions are completely unusable.
  • Don't approve revisions just to give credit to someone - It's better to work with someone in the discussion forum to come up with a better revision. New contributors that are not participating in the discussion forum will be contacted by a SUMO admin in order to facilitate this process. Note: We need to fix the way credit works (Bug 628634). Approved revisions based on unreviewed or rejected revisions should give everyone credit. This will eliminate the motivation for this issue.

Ready for localization

Marking an article revision as "Ready for Localization" lets us tell localizers that the English version is done being worked on 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 article 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 Fireofox 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.

Adding and removing articles

Proposing new articles

Our knowledge base is what makes our entire support effort scale to serve hundreds of millions of Firefox users. The most efficient thing we can do is answer peoples questions about Firefox with an article. But articles don't come without a cost. Each one has to be written, localized and maintained. With many features and issues already documented it's often a better use of our collective time to make existing articles better.

Factors to consider before creating an article:

  • New features - User facing features that are likely to generate a lot of interest and questions from users. This may be an inherent aspect of the feature, a result of marketing and in-product links or a combination of the two.
  • New issues - Issues that have many recent threads and votes in the support forum and Live Chat.
  • High impact - Critical, time sensitive issues that need temporary documentation (e.g. Pogo.com and other Java pages don't work)


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.

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

  1. 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.
  2. 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.
  3. Create and draft the article.
  4. 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.

Archiving articles

We'll periodically archive knowledge base articles to keep our focus on users' most pressing items. As we release Firefox every six weeks the issues and items that users will need documentation for will change at a much faster rate. There will be a lot of articles (like How do I use bookmarks? or How to set the home page) that will stay around for a long time but there will others that become obsolete or not of concern for users. Ideally, we should have about 175 articles. That will allow us to document things in enough detail while being small enough to maintain and localize.

How it works:
Contributors with reviewer privileges can mark an article as obsolete by editing the description section of an article. This will remove the article from all dashboards (including localization dashboards) and from the normal search. You can still see the article by using the advanced search, and of course links to the article would be preserved. However there will be a banner on top of the article making it clear that the article is no longer maintained and might be out of date.

Archiving an article is not a one-way street. Once an article is archived we will monitor the stats, to make sure that the article wasn't a popular one. In case we made a mistake it's as easy as clicking a checkbox to get the article back on the dashboards.

Factors to consider before archiving an article:

  • Low views - Generally, articles with less than about 1500 visits/month.
  • Few recent reports - Issues that have relatively few recent threads and votes in the support forum and Live Chat.
  • Low impact - Removal of the article is not likely to cause or exacerbate a serious issue.
  • Changes to Firefox - Instances where an issue has been fixed in Firefox or a change in Firefox behavior has made something obsolete.