You can use this checklist when you plan, write, and review documentation. Some points might not apply to your company, but all of the ideas are worth considering.
If you have comments, contact me at: mbehm@redhat.com
The title is:
For example, if your ordering system has a 40-character limit, confirm that the manual can be uniquely identified within 40 characters of text.
The manual's version number is visible from the outside of the manual. Your packaging people will need to confirm that the manual version matches the software that it will be shipped with. They will not want to open the shrink-wrap to do this.
The part number is correct.
The supported version of software is clearly marked.
The manual is usable. For example, if you expect the reader to read a few sentences then type some command or click on the interface, does the manual lay flat or does the user have to type with one hand? Your users may not be touch-typists. If the readers look away from the page to look at the screen and then look back, are there visual cues that help them find their place?
Pages look "appealing":
The structure is consistent: similar information is organized and presented in a similar way.
Important information stands out on the page. For example, warnings (which warn of the potential loss of data) are easy to see.
If the manual is a revision, new information is clearly identified. Not many companies use change bars, perhaps because not many systems implement change bars well. However, you do need to ensure that existing customers can learn what is new in the new release.
Reference manuals have running heads. More generally, be aware that Support groups often fax manual pages. Any well-designed page should have headers and footers that indicate where the page came from.
Each chapter has a tab divider or bleeder tabs.
Each "book" in a multi-book binder has a tab divider that is distinguishable from "chapter" tabs.
Text on the tab divider is the same (or is clearly derived from) the title of the associated section.
All links, phone numbers, and addresses are correct.
All references to other manuals and products are correct.
Spelling, punctuation, and grammar are correct.
The artwork and screen captures (including captions) are correct.
Analyze the manual at the level of paragraphs and sentences:
Each paragraph has one main idea.
The paragraph's main idea is expressed in the topic sentence, and this is the first sentence in the paragraph.
All paragraphs are less than half a page.
Transitions between topics are smooth.
Sentences are simple without being terse. Sentences are generally less than 25 words in length. Shorter sentences avoid ambiguity in the relationships between elements in a sentence.
Most sentences do not have subordinate clauses.
The subject of each sentence is clear. Referents (such as pronouns) are clear.
The document primarily uses the active voice.
The passive voice is used appropriately (and not to hide ignorance).
Instructions are given in the imperative voice.
Sentences generally do not begin with a present participle or past participle.
The language matches the audience's vocabulary and experience. Assume that what you are writing will be read by people whose first language is not English.
The manual speaks to its audience (using imperative verbs or the second-person pronoun). The manual avoids using third-person constructions (for example, "the user does such and such").
The manual primarily uses the active voice. The passive voice has a place, but try to use the active voice.
Pronouns refer to only one antecedent.
There are few modifier strings (such as noun strings). Compound phrases contain no more than three words.
Wrong: XXX is the process's current event-monitors' status list.
Right: XXX lists the current status of all event monitors for this process.
Articles and "optional words" (such as "that") are used to avoid ambiguity.
Words are not used in multiple grammatical categories.
Use "during the restore operation" rather than "during the restore".
There are no unqualified references to toll-free telephone numbers (include "within Canada" or "within North America" as appropriate).
Date formats are not culture-specific: extended versions of the date (May 8, 1945) are used whenever possible.
Sentences do not contain too many prepositions.
Wrong: XXX is a list of the current status of all event monitors for this process.
Right: XXX lists the current status of all event monitors for this process.
Spelling and grammar are accurate.
Spell check, obviously. But more than that, watch to see if there are mistakes you make that are actual words but improper in the current context. For example:
As for grammar, you might be able to run your text through a grammar checker. Say that you work in FrameMaker on a Windows PC: Copy your text into a flat editor to remove formatting. (You might copy the text (or an HTML version of the text) into Notepad, for example.) Copy the flat text into a program that has a grammar checker (for example, MS Word). Make the appropriate changes to the source files. I'd appreciate a non-Windows example, if anyone could provide one.
Terms are used consistently.
New terms and acronyms are defined when first used. It can be difficult to determine just what "first" is. You cannot guarantee that your reader has started at page 1 and is reading through a page at a time.
There are no occurrences of contractions, telegraphic style, Latin, slang, jargon, humor, sarcasm, colloquialisms, idioms, metaphors, images that have hand gestures, images of animals or references to animals, cultural references, and gender-specific roles.
Terminology is consistent in the software, the online help, and the printed manuals.
There are no references to culture-specific standards. (Use metric dimensions first, then culture-specific standards (inches, furlongs, li, cubits) when necessary.)
There are no culture-specific symbols (' for feet, " for inches).
There are no "and/or" constructions (this does not exist in other languages).
There are no (s) or (es) additions to indicate the possibility of multiple occurrences.
There are no abbreviations or acronyms.
If you will translate your manual, ensure that:
There are no hard-coded page breaks (translated text will be 15% to 35% longer).
Table columns are wide. Words in certain languages are much longer than English, making narrow columns in tables very difficult for text in German and Russian.
Graphics do not contain text (use numbered call-outs instead).
Graphics are linked, not embedded.
Graphics are anchored to maintain their relationship with the associated text.
Graphics files have names that reflect their usage (fig01-03.gif for figure 3 in chapter 1).
Instead of applying a formatting override, a new style is used.
Conditional text is not used within a sentence; duplicate the sentence and make each sentence conditional in the appropriate way.
The organizing principle (how-to, reference, quick reference) is appropriate for the manual's function.
The document's elements progress in logical ways:
From simple to complex
From general to specific
From topics of wide interest to topics of specialized interest
From known to new.
The document is complete.
The document covers only appropriate topics (based on the purpose of the document and the audience for the document).
The order of presentation reflects the order of use.
If the manual contains both tutorial and reference information, the two types are kept distinct.
Topics of general interest are presented before those of limited interest.
There is no extraneous information. This is a subtle point. In the course of learning about the product, you may need to teach yourself information the audience already knows. For example, if your software supports accounting tasks, you might write basic accounting information that you have learned (but which would be completely obvious to your audience). When you review the final version, ensure that you really have written to your audience.
There is an introduction that provides a framework for the information in the chapter.
Each major section has an introduction.
The order of information within a chapter makes sense (for example, are requirements presented before actions).
The heading levels are appropriate for the detail of the material.
Information is organized so that minimal cross-referencing is needed. If you are pointing the user to required information, make certain that you can't just move the referenced information to where the cross-reference is.
All cross-references point to useful information. In a printed manual, once readers are directed away from the current page, you are relying on them to find their way back. If you have written a manual that requires a linear flow of information (for example, "system requirements -> installation -> installation verification", you really want to avoid taking the user out of that series of tasks.
The Copyright Notice (including the date) is correct.
The Preface describes the contents and the audience.
The document conventions are listed.
If required, there is a documentation map.
The document provides the reader with a way to contact you with comments.
The document provides the reader with a way to contact the Support group.
All notational conventions are described.
Notational conventions are used consistently.
The manual has a Table of Contents that lists the chapters and first level titles (and perhaps second level, if appropriate). There are lists of tables, lists of figures, and lists of examples. Think very carefully about whether anyone would ever look at a list of tables, figures, or examples to find information. Personally, I find it difficult to imagine.
You may want to have a Table of Contents for each chapter, listing first, second, and third level titles. If you do not want something as formal as a TOC for each chapter, you may want to include an introductory section that describes the chapter contents (including page references). This is particularly useful for online manuals.
The chapter names reflect the chapter contents. The order of chapters makes sense.
All titles contain clear terminology. Also confirm that the headings use consistent capitalization and grammatical structure.
All task-oriented sections have task-oriented titles. (For example, "Shutting Down the System".)
All concept-oriented sections have concept-oriented titles and have terminology that is familiar to the user. ("About System Security")
All reference sections have feature-oriented titles. (For example, command names.)
Each heading reflects that section's contents. During reviews late in the development cycle, confirm that the text still corresponds to the title. The text often evolves during the course of development--you may need to resync the title. If you are creating hypertext, ensure that the launching text matches the text at the other end of the link.
Consider these characteristics for each chapter.
There is an advance organizer at the beginning of major topics. Each H1 and H2 section should have introductory information. Note that in most documentation (particularly in user's guides) each heading should be followed by some body text and not by a consecutive heading.
Analogies and similes are used effectively to explain complex, difficult concepts. You should also consider using graphics.
How-to discussions and tutorials have a task orientation. For the new writers, the difference between product-oriented and task-oriented can be subtle. Take the idea of printing from a GUI: don't you just go to the Print screen, checks the fields, and click OK? Not quite. The task of printing can include installing the printer drivers, setting the default printer, setting the default print options, "printing", and troubleshooting a failed print operation. You do need to describe how to access and use the Print screen, but that is just a part of the printing task.
Each task description includes:
The purpose or goal (in the user's terminology)
Setup (prerequisites)
Process (step-by-step)
Results (feedback)
Error recovery
"For more information" references.
The sequences of tasks in the manual matches actual customer use.
Tutorial and how-to discussions are appropriate for the audience:
Begin at the appropriate level
Define new concepts/skills
Present information from the general to the specific
Pace the information appropriately.
Information is presented in "digestible chunks". The length of each task discussion is appropriate. Complicated tasks are broken into smaller units.
Reference material is organized in a way that enables the reader to locate information easily.
Reference discussions have a feature/concept orientation. One of the weaknesses of this checklist is that it doesn't really discuss the quality of information.
Each feature description includes:
Syntax description
Example of use
Where to find added information.
Reference discussions follow a consistent, reliable sequence.
Required and optional parameters are distinguished from one another.
Tables are used where appropriate as an alternative to prose discussions.
Tables are placed close to their associated text.
The structure of the table makes an effective presentation of its contents. Ensure that the table starts with the known information and moves to the unknown. For example, my Cable company provides a channel-mapping table for the back of a remote control:
PRESS
TO RECEIVE
02
.........TVO 28
03
......Global 06
04
........CFMT 47
05
...CBLN(CBC) 05
06
...WKBW(ABC) 07
07
......CityTV 57
08
..CBLFT(CBC) 08
What this table tells me is that when I press 06, my TV shows the ABC station from Buffalo. While this is true, it is also pretty useless. As a viewer I begin with a broadcast schedule that tells me that a Star Trek rerun is on now on channel 7. I need to scan the right column then map backwards to the left column to learn that I need to press 06. As you can see, the right column is in a more-or-less random order. The most annoying part of this is that the Cable company at one time did the listing properly!
Sufficient examples are provided. This is particularly useful in online manuals. In manuals that describe complex command syntaxes, readers often want to copy a particular example, make a few changes for their needs, then run it.
A progression of examples supports a task.
Examples support both basic and complex aspects of features or tasks.
All examples work. Test them!
Examples are placed close to their associated text.
The error messages the product displays match those given in the manuals.
Appropriate illustrations are provided.
A progression of illustrations supports a task.
There are no typos in the graphics (including screen captures).
The screen captures match the released product.
Illustrations are placed close to their associated text.
Key terms and acronyms are defined in a glossary. The glossary should contain only terms used in the manual.
A manual set map is included in each manual.
The map clearly depicts the recommended reading sequence for manuals within the manual set. I once received a product that had two "Read Me Firsts". Make sure that you know where your manual fits in the whole documentation set.
Information in an appendix is supplementary or is used by a small portion of the audience. For "a small portion," say 20%. Note that the obvious corollary (the body of the manual should contain only information used by a majority of the audience) is also true.
The manual has an index!
Every major user task is listed under an "industry standard" term.
Every major concept is listed under an "industry standard" term. (Generally I index nouns and use subentries for verbs and gerunds. However, I make exceptions for standard tasks such as printing.)
Every major product feature is listed under an "industry standard" term. Think about this for a moment. It means that you have done your competitive analysis and know what terms are standard in the industry. If you do not control the terminology used at your company, you must at least provide users with a way to map the terms they are familiar with to the terms your company uses.
Appropriate index entries have synonyms.
The index has:
Typographical consistency
Organizational consistency. Ensure that you standardize on the form of entries. For example, do not have entries for both "file" and "files".