Thunderbird:Help Documentation:Style Guidelines
The guidelines for how Help documents should be written fall into two main areas: language and coding style. Because the coding style issues are more applicable to when the documents are actuallly in the mozilla.org tree for building, most of the issues covered will be those of language. These guidelines are based upon those listed in the Resources section below. However, they differ in some areas, so you shouldn't need to refer to the originals unless you're redirected there or you're just curious what they say.
Take a look at existing Firefox Help documentation if you want some examples of the style we want.
Contents
Language
Keep it clear, structured, and generally useful. If it's something that the average user isn't likely to do, it probably shouldn't be in the built-in Help. The excellent Thunderbird Help site and other such resources are available for the power user. We can't fill every need because of space restrictions, so we should let other resources fill them.
The voice of Help documentation is enabling, authoritative, and friendly. We're focused on helping the user do what he wants to do. We should sound authoritative yet friendly. That's the basics of it, but you should probably look at the Voice guidelines to get a fuller idea of what is meant here.
It's "Mozilla Thunderbird" -- usually once per article. Refer to the application as "Mozilla Thunderbird" once at the beginning of each document and in the article title (if you'd want to refer to the application by name), but after that refer to it as "Thunderbird". Don't call it "the application", "the mail client", or anything similar -- we can keep Thunderbird's branding fresh in the user's mind by calling it what it is.
Links make sense, both in and out of context. Don't use "click here" as your link text.
Use the text from the UI. If the menu item's written a certain way, then you should write it out that way, capitalization and all.
Spell things right! Spelling and grammar are somewhat nitpicky, true, but I guarantee you'll find a user who's put off by such mistakes. Try to keep things good by yourself for now, and when docs start getting added to the main mozilla.org source code, we'll go over them again to make sure everything's right. (I have an eye for what's wrong, and others will be helping as well.) Also, if there are multiple ways to spell something, choose one way and spell it that way consistently.
Format
Start with a summary. At the top of each general help topic should be a summary of Thunderbird's capabilities in that area. This gives the user an immediate idea of what areas the help topic covers, and therefore whether (s)he's looking in the right place. Remember, many users who consult inline help are doing so because they have a good idea what they need to do and want to find out if Thunderbird can do it. Only once this question is answered do they need specific instructions on how to do it.
Make it task-based. Most users dip in and out of help topics to find specific instructions for specific tasks. So break each topic down into the relevant key tasks, then use numbered step-by-step instructions to describe how to carry them out.
Coding
Don't use wiki markup! We won't be able to use wiki markup when the docs get added to the source code, and most HTML markup is still valid in this wiki.
Use wiki markup for links! Link directly to the location of the page, like so: [http://wiki.mozilla.org/index.php/Thunderbird:Help_Documentation:Style_Guidelines Style Guidelines]. When the docs get moved over into the main tree, we'll do a search for "[http://" to find instances of wiki links. It's pretty bad, but at least the links will be testable without edits.
Don't manually wrap lines! Let them get wrapped by the wiki. It looks bad in the wiki, and wrapping them for when they go on the mozilla.org site is relatively trivial.
