Six Tips for Improving Technical Writing Technical writing isn't magical. It's the nuts and bolts behind documentation that help users use products. Sound simple enough. But imagine this: You get the latest version of software, and it is not intuitive, no matter what the marketing blurb says on the box. You turn to the documentation - a thick book filled with screenshots and text that "walk you through" the program. Fine, you say, I will just read this book cover-to-cover for the next three years, and then I will be proficient. Well, who has time for that? Poor design can't be fixed through documentation, especially documentation that is longwinded and cumbersome. The sad news is that few people even crack the book. And if a product is hard to use, it will be hard to explain to others how to use it. So what's a technical writer to do? 1. Become a User Advocate If you are a technical writer, your new role must become a user advocate, and you need to make a point to let developers know that what they are developing is difficult to understand or use. In essence, developers need to make their products user-friendly. How does taking on this role help? -This makes your job easier, if your job is to document a product or train others on its proper use. - It makes the developer's product better through testing and support. - It makes your customer's life simpler, because the product will become easier to use. How can you become a User Advocate? - While it's early in the development game, get involved in the process by offering support and suggestions. - Do your homework. If you can provide user standards and industry guidelines to a developer, you are that much closer to winning your way. - Test, test, test. And tell the developer what you find works, and what doesn't. This refines the product and makes it better for everyone (developer, user and you, the documenter). While all of this takes time, it's worth it to see better products developed - and better products are easier to document and use 2. Online or Off? With Internet capabilities being what they are these days, putting product information and documentation online can reduce product costs, provide quicker turnaround and increase timeliness of updates. Regularly, web pages, online help and PDFs of instructions can be found online, ready and available with just a touch of a button or two. Yet, not all types of documentation are suited for the World Wide Web. Consider the following: - Installation instructions. Users generally need and like to have them in front of them during the installation. - Large documentation manuals. Users generally don't read online full texts, and comprehension is less when text can't be read over, as in the case of a web site that is updated daily. Online documents have roughly half the readability of printed material. - Troubleshooting information, because the explanation may require using the system being patrolled for trouble. According to users, most users actually prefer printed documents, and if you include an option to download text to be printed at their expense, you can have it available to them both ways. 3. It's All in the Wording Consistency counts in business and technical writing. The words you use throughout the document set a standard for that consistency, making the documentation and products easier to use. So, how can you ensure consistency? - Write a glossary about the product first. Then refer to the glossary for standard work usage to increase consistency. - Pick one term and use it throughout the documentation. Whichever phrase you choose will become the standard. - Use the words that are in the product. - If you work with architects or engineers, help them to use the same terms consistently so that updating docoumentation and answering their questions will become easier over time. 4. Step-by-Step Instructions If your task is to document a series of steps in a windowed operating system, here are some steps to make it easier on you and on your reader. - Write steps and commands in order of appearance. This path is easier for readers to follow, and quicker for you to write. - Write out the full path of instructions to simplify matters. "From "Tools" on, select "Options", select the "Spelling and Grammar" tab, then under "Grammar", check "Show Readability Statistics" and select "OK". - Write in simple terms (no need for "From the dropdown menu under options"). - When you have room in your documentation, add screen shots for clarification ("Your screen should look like this.") - "Select" or "click" - you may have a preference for one or the other, but as with other terminology, be consistent for readability. This consistency will become the basis for your documentation style manual. - Be a user advocate. If you are having a hard time explaining something, users will probably have a hard time reading documentation and using the product. Contact developers to make products more user friendly. 5. Creating Style Guides How many times have you found yourself scratching your head wondeirng, "What did I do the last time this issue came up?" What you need is a style guide. Style guides: - Help create consistently written documents. - Solidify your use of proper grammar, terminology and format. - Provide rules for formatting graphics in publications - Outline the proper use of company logo, trademarks, registrations and industry-specific terminology. - Save you from reinventing the wheel on each project. To help you get started, check out various published style manuals. The most commonly used are the Chicago Manual of Style and Microsoft Manual of Style for Technical Publications. They are just a starting point, as you will want to develop your own style guide based on the type of projects you work on regularly that you may not find answers to in these texts. In creating your own guide, remember that it is a "living" document. In other words, you will want to change it and update it often as your knowledge increases or your needs change. This is the kind of document that could be part of your company's intranet resources so everyone has access to proper styles required for pubilcations. 6. There Be No Dummies ... Is is said that Christopher Columbus stated, "There be no dragons" to a frightened crew as they sailed toward what was thought of as a never-reachable horizon. Despite what the sales figures might suggest about the "For Dummies" series of books, there really are few people who actually like to be called "dumb". Often, the trend to "dumb down America" is touted as media's failure. This trend has to stop somewhere, so it might as well start with you, the writer of technical information for new users of the product you are documenting. To make your readers feel smart for purchasing the product and even smarter once they read your documentation, follow these simple steps: - Learn everything you can about the users through focus groups. Understand their skill levels, and figure out what they need to know in order to use the product you are documenting. - Products are dumb, not users. If a user can't use a product after being willling to read the documentation, then the product is not user-friendly. Here's your chance to become a user advocate: Let the product designers know what works, and what makes their product hard to use. - Focus on the task users want to accomplish and speak to that purpose of completing the task in your documentation. This kind of task-oriented writing helps them become successful and smart about a product, all thanks to your clear writing ability. - Remember that users may want to know more about the product than just how to use it. It's like sailing: It's one thing to ride in a boat, it's something completely different to understand how the wind propels a boat by pushing wind on either side of a sail, and the slightest change in the angle of tack will increase or decrease speed dramatically. - Documentation is meant to be used, so make it available and easy to read. Offer different forms of text (on the box, in a book, online, separate installaton instructions, pop-up menus if you are working with computer software, etc.). Be consistent and clear in your writing, and you will do your part to help the user feel smart about using a product that you documented.