Richard Taylor - Documentation for Dummies

Posted September 1 1997

Printer-friendly version

Richard first did a little bragging, citing quotes from PC Week authors Peter Coffee and Bill Machrone where they found the Clarion documentation exemplary. He then introduced the people who helped him produce the documentation. This included Jim DeFabia and John Broadwater. These are people who can both program and write. Throughout his presentation, Dilbert cartoons appeared to spice up the points he was making.

The Dummies Books

Richard had three Dummies books, the one for Clarion, the one for Delphi, and the one for C++. Using these three he asked what they did right. Each of the books had on the cover statements that the book contained "The Fun and Easy Way to..." learn the relevant topics. Each announced on the front cover that it was written in plain English. On the back cover, three icons indicated when to watch out for Technical Stuff, Tips, or Warnings. Just because a book is technical doesn't mean it has to be boring. (The Dummies books have a joke on nearly every page.) This involves walking a fine line of whether to go for the joke, or bore people. Indeed, there is a thing called Edutainment, which is the marriage of education and entertainment.

Start with....

Richard recommended we start with the basics. Make no unstated assumptions. Each of the Dummies books defines who the people are that are reading their books. For example, the C++ book assumes that the reader has a working knowledge of C. If he doesn't, he is told to quietly put the book back on the shelf, and take the C for Dummies book. Manuals should always start simple and build to the complex, starting perhaps with things already understood. Limiting your scope keeps each "chunk" in an atomic unit so the reader does not have to go to other places to find out the complete picture. He suggested no forward references; i.e. references to future parts of the manual that will contain more detailed descriptions of things only alluded to 'here.'

User Manuals

Manuals must explain how to use the product. This should include the big picture of what the product is trying to accomplish. How this software fits into the rest of the reader's world. It should also include task-oriented approaches to teaching how to use the product. Thus a tutorial with examples is extremely valuable. The writer should put himself in the place of the user.

Online Help

Online help should differ from user manuals. It should be context sensitive (providing help on the current screen only) with perhaps jumps to related topics. In Richard's opinion, printed documentation and online help should not be the same. Just printing the help files as the printed documentation is a very poor substitute.

Plain English

Some hints were discussed about using plain English. Simple declarative sentences are preferred. The goal is to communicate, not impress people with the command of the English language. Present tense is best. Active voice is best. He mentioned that in Word for Windows, sometimes the active voice is turned off in the grammar checker. He suggested turning it back on. Acronyms and buzzwords should be kept to a minimum. Always define new terms the first time they are used.

Organization

The layout should include proper fonts and white space. Leave some white space on each page - if not, you are providing information density. A readable font is between 9 and 12 points. Richard uses Times for the body text (at 11 points). Most word processors provide adequate vertical space between lines. Richard suggested fonts with serifs be used for the body of the text, either Times, or Times Roman. For headings, he suggested a bold face sans serif such as Helvetica. Regardless of what you select, be consistent between pages and paragraphs.

Remembering

Structurally, tell people what you're going to tell them. Tell them. Then tell them what you've told them. Studies have been done which show that of the above three steps, the summary will be remembered the most. The introduction will be remembered the second most. The details in the middle will be remembered the least.

Summary-What the Dummies books do right

They keep things entertaining; they keep things simple; and this combination results in education almost by accident.

Article comments

Post a comment

You must be logged on to post comments.