OVERVIEW Most product documentation sounds like their product is the only thing in the User's life. Such thinking results in User confusion and dissatisfaction. This article presents three real-life examples of this attitude, and what should be done to remedy these unfortunate situations. The article concludes with some techniques for the writer. BACKGROUND There are two important facts that User Documentation ignores: 1. Your product is a only minor item in your ...

OVERVIEW Many organizations produce in-house tools or modify commercially-available tools for their own use. These tools should get documented so they are of use to others in the organization. If this documentation is not created or is poorly written, it costs you twice: * The first cost (attributed to any poor user document) is the cost of answering the Users' questions (technical support). * The second cost, arises from the lost time of your employees trying to...

OVERVIEW To create an effective User Document, the writer must know who he/she is writing for. This article presents four dimensions (Skills, Attitude, Knowledge and Experience) for describing the User of your product (your Documentation Reader), and how to build a Persona that turns your generic User into an almost-real person. The article stresses the need to actually USE this information when structuring and writing your User Document. GETTING INFORMATION ABOUT YOUR ...

Overview Our humdrum, sterile headings and writing manner do little to encourage our Users to read parts of the product documentation that would be especially beneficial for them. This article presents two real-world examples, how they fail their users, and how to correct the problems. Not the Legal & Disclaimers Although the Legal and Disclaimer sections of your documentation are important for the protection of your company (and protection of your company should be ...

Overview Incomplete User Documents disappoint your Readers. Two attitudes of many Technical Writers result in incomplete User Documents. These two attitudes are: . "Everyone Knows That", and . "The User Can Figure It Out" This article describes these attitudes and presents methods for overcoming them. The result is more effective User Documents and more satisfied Users. 1. "Everyone Knows That" The "Everyone Knows That" attitude makes assumptions about your ...

Technical writing requires the ability to write clearly, plainly, and accurately about extremely complicated material. If you can do that—and quickly—then becoming a successful technical writer is well within your grasp. The most common clients for freelance technical writers are educational firms, training companies and manufacturing/electronics/software companies. All of these demand a high volume of documentation-style writing, and thus a high volume of technical writ...

OVERVIEW In your User Documentation, you direct your Reader to perform tasks with your product. If you don't tell your Reader what to expect when performing those tasks, you will have a baffled Reader, resulting in dissatisfaction and expensive calls to technical support. EXAMPLE: REVERSE OSMOSIS WATER FILTER I bought and installed a Reverse Osmosis water filter. The instructions told me to fill, and then empty (the instructions foolishly used the term "dump," which ...

Overview Your editor should be an integral part of your writing team. Do not think of him/her as a judge, but rather as a resource to help you in all phases of the writing project. This article will help you overcome any fear of your editor, and how to effectively use your editor during the writing process. Beware of Your Editor Some of the changes that an editor might suggest could make the User Document more difficult for your Reader to understand. Improving You...

OVERVIEW A good User Document includes sections on how to set up, use, and care for the product. However, to create a great User Document , the technical writer should use the Persona, generated in the analysis of the User/Reader, to create the topics for the most useful section of the User Document. This article describes this procedure. THE MOST USEFUL SECTION OF A USER DOCUMENT The most useful section of a User Document is the one that helps the User get what he...