Documentation Guidelines

Jump to: navigation, search

When writing documentation, there are a few guidelines that you should keep in mind:

  • Provide an overview, structured in the same sequence as the material that will follow, that tells what the feature is for. Keep this section at a high level of abstraction; for example, do not describe all the options and variations.
  • For readers in a hurry, provide a quick reference section. Think: What do you always find yourself looking up?
  • Begin each sub-section with a more detailed overview, explaining what the feature does in more detail, including where you go to start, what you have to do, how it works (briefly, and what options are available. (You will probably have to test the feature to find out. There are tons of undocumented features! Talk to developers and examine the code, too.)
  • Remember, people don't read on the Web. They scan! Make your text more readable by doing the following:
    • ALWAYS use a numbered list, with step-by-step procedures, for ALL the procedures you describe.
    • Use white space effectively.
    • Be sure to follow the Documentation Conventions, described below.
  • Ultra-important: Think of everything that can go wrong! ALWAYS include a troubleshooting guide for EVERY section, and tell how to SOLVE the problem.
Personal tools