Support:Best Practices for Support Documents

Support » Best Practices for Support Documents

We want Firefox Support to be usable by most Firefox users, which means there is a computer literacy barrier that we need to overcome, when writing Firefox support articles. Our target reader is someone who does not know how to use about:config, or add a toolbar button, without instruction. This means each article should not only provide answers, but instructions, and assume the users has kept all settings at their default values. In general, try to write articles in such a way, that your mom would understand.

Write articles that are useful to 2.0 users. Firefox 1.5.x has reach its end of life; and the major update has been pushed.

It's amazing how some users can misinterpret instructions; so when describing actions, try to word it in a way that is brief, yet cannot be misinterpreted (words are expensive).

The word "user" itself is a technical term. Try to avoid phrases, like "If a user has lost his bookmarks." Word your sentences, as if you are speaking to the user, like "If you've lost your bookmarks..."

The title of the article describes the question being asked or the problem being enquired about.

• Good: Toolbar keeps resetting
• Bad: corrupt localstore.rdf

Give a brief (one paragraph max.) summary of the cause of the problem, and what is being done (in the article) to fix it. This is your introduction. There's no need to name it as such (or "Background").

Users only need one answer to their question. There are cases in which there is more than one way of accomplishing a task. In such instances, try pick the most user-friendly method. In general, the order of preference is:

1. The graphical user-interface (menus, check-boxes, buttons, etc.) distributed with Firefox.
2. If it's a preference, that the user is likely only to change once, use about the about:config method
3. Extension
4. User script (user.js, userChrome.css, userContent.css, etc.)

If none of the above are possible, there's usually one method of accomplishing a task anyway.

When providing step by step instructions, use a numbered list, rather than bullets.

Include expected results, when giving instructions (e.g. Choose the Firefox (Safe mode) menu option. A dialog will appear.)

Instructions directing a user to an item in the user-interface should be full sentences.

• Good: At the top of the Firefox window, click on the Tools menu, and select Options..."
• Bad: Go to Tools > Options...

Instructions for practises which breach net etiquette, should make a note of it, not make the user feel like a sinful criminal.

Multimedia

Screenshots

Don't be shy about including screenshots. Try to include a screenshot(s) that will help clear any potential misunderstandings of the article text.

• Screenshots needs to present Firefox in its most familiar form, which means using as many default settings as possible, including the default Firefox theme, and default operating system theme.
• Crop what is needed, but make sure the cropped image is still identifiable. If you need to create an image of the full screen, use a resolution of 800x600 (just so the image doesn't take a lot of space, without need).
• When highlighting sections, draw red lines around the section.
  • Good:
  • Bad:
• If it doesn't make the image unreadable, decrease the size to 75%
• save for web, in PNG 24 format

Videos

• Videos needs to present Firefox in its most familiar form, which means using as many default settings as possible, including the default Firefox theme, and default operating system theme.
• Provide a text version for those without hi-speed
• If there's no need for a voiceover, don't bother (saves on video file size)
• Flash format is preferred