Examples & Style Manuals

Use Examples

Another technique for illustrating and teaching is to use examples. While users eyes may glaze over as you explain function after function, they'll tend to pay attention if you show real people solving problems with the product at hand. Giving your example users names and perhaps illustrated faces will add to their appeal. This approach can easily be overdone. Adult learners don't necessarily want to stay with a manual that reads like a storybook. But judicious use of examples can help users visualize themselves as successfully using the product.

Use Correct Spelling and Punctuation

The most intelligent, well educated writer can look like an idiot if he doesn't take the time to check for correct spelling and punctuation. Some people are naturally good at spelling, some aren't. Some people know exactly when to use a semicolon instead of a comma, and some don't. For those who need extra help, there is the dictionary and your word processor's spell check feature. Remember, though, that passing the spell check doesn't guarantee that your content is error free. Computers often miss typographical errors resulting in words that are spelled correctly but used incorrectly. If you write "Turn of the power" instead of "Turn off the power," your computer won't notice the mistake. Computer spell checking should always be accompanied by careful human proofreading, preferably by more than one pair of eyes.

Reference Books and Style Manuals

Even the best writers usually have a punctuation rule that they routinely forget or a word they can never remember how to spell. Proper use of punctuation is a fairly dry subject that most people don't pay attention to until they have to. For these reasons, having a library of style manuals and other reference works can be indispensable for the technical writer. Here is a selection of reference books that most writers should own.

The Elements of Style by William Strunk and E.B. White, Longman Publishers, 1959, 1972. A timeless classic of a book that sets out the rules for writing clearly, concisely, and effectively.

The Chicago Manual of Style, 15th Edition, The University of Chicago Press, 2003. An exhaustive, brilliantly done guide to everything from printing a book, to publishing a web page, to figuring out whether to use a hyphen or a dash.

Handbook of Technical Writing, Ninth Edition, by Gerald Alred, Walter E. Oliu, and Charles T. Brusaw. St. Martin's Press, 2008. A reference guide geared specifically toward technical writers, the Handbook covers style elements specific to technical projects, shows examples of the types of documents that technical writers work on, and offers an extensive alphabetical list of common elements of technical writing.

Other style manuals, such as those covering AP news writing styles, can be helpful as well. There are also style guides covering APA and MLA style for writers of academic research papers. While these formats are less useful for technical writers, from time to time they may come in handy.

]]>