| Summary |
|---|
Good technical documentation makes ample use of two types of lists:
|
Most readers like lists. In fact, one of the best selling books of the 70s was called simply, The Book of Lists. Think of the enormous popularity of David Letterman's Top 10 List.
Technical writers should honor reader preference by sprinkling lists liberally in technical prose. Note, however, that technical documentation consisting only of lists will usually fail. A mixture of traditional prose and lists works best.
HTML supports the following three kinds of lists, which are pretty good categories for this discussion:
The list of three elements that you are now reading is a definition list. (We'll skip over definition lists for now but revisit them during the final class.)
Numbered lists document events that must happen in a certain order. Use them to describe a sequence of steps. Numbered lists are extremely useful when giving directions. Numbered lists can also document order of preference, such as a ranking of the top 10 students in the class or the top 25 basketball teams.
Technically speaking, David Letterman's Top 10 List should really be a bulleted list. Even Mr. Letterman acknowledges that No. 1 no funnier than No. 10.
Once in a while, particularly during a lecture, you can turn a bulleted list into a numbered list if you need to refer to specific elements of that list later on. For example, "Let's look at point 3 again."
Elements in a numbered list should usually start with a verb.
By the way, a numbered list can cross-reference other elements in the list. For example, "If you don't see an image in the microscope, repeat step 2."
Perform the following steps to pull away from the curb:
Technical documentation is ordinarily thick with bulleted lists. A "bullet" usually looks something like this:
The citrus family includes the following varieties:
Notice that the preceding list has no obvious order; therefore, it should be a bulleted list rather than a numbered list.
You must introduce all lists. The introductory sentence should end with a colon. As a rule of thumb, put the word "follows" or "following" in your introductory sentence.
By the way, never use the word "below" when introducing a list. Lists have a nasty habit of sliding to the next physical page. Thus, the list might not really be "below" the sentence that introduces it.
| Good | The following recipe makes a hearty tofu lasagna: |
| Bad (don't use "below") | The recipe below makes a hearty tofu lasagna: |
| Bad (don't use fragments) | A hearty tofu lasagna: |
Each element in a list should have the same grammatical form. For example, if the first element in a list is a singular noun, then all elements should be singular nouns. If the first element is a complete sentence, then all elements should be complete sentences. If the first element in a list starts with a verb, then all elements should start with a verb (in the same tense).
Beyond simple grammar, each element in a list should logically belong.
A list in which each element is grammatically consistent is said to be "parallel" and naughty lists that don't follow this rule are called "nonparallel."
Be consistent in the punctuation that ends each list element. I'm not strident about what punctuation you use, just as long as you use it consistently.
Each element in the following parallel list is a verb phrase:
setup.exe.
The following list is nonparallel because the third element belongs to a different category than the first two:
The following list is nonparallel because the third element is plural and the first two elements are singular:
The following list is nonparallel because the third element ends with a period and the first two elements do not:
The following list is nonparallel because the third element does not start with a verb:
setup.exe.