Visual Aids & Style
Use Visual Aids
Technical writing isn't just about words. "A picture is worth a thousand words." says the old cliche. Nowhere is this truer than in technical writing. Illustrating user documentation with photographs, drawings, charts, and graphs can greatly enhance your user's experience and help them learn to use your product better and faster. How many words does it take to tell a user where the on button is, and when you're done can you be certain they have understood you. A good drawing of the product with a red arrow pointing to the on button, on the other hand, leaves little room for doubt. With software based help and online help, technical writers can now go beyond the drawings and black and white photos traditionally used in manuals, and provide full color photos, animations, and movies. Screencasts that show exactly where to move a mouse can make software-user-help ten times as effective as can a printed manual. Remember to illustrate your documentation wherever and whenever you can.
Style and the Technical Writer
Technical writing is not literature. It is no one's idea of great art. It is simply useful information delivered in a usable fashion. But that doesn't mean technical writing should be boring, quite the contrary. When explaining complex subjects, engaging, lively, readable writing can help a reader stay with you and learn what they need to know. While writing Shakespearean iambic pentameter is definitely not required, here are some stylistic elements good technical writers weave into their work.
Go for Variety
Vary your sentence lengths. Follow a long sentence with a couple of shorter ones. Vary the rhythm and flow of your words. If all of your sentences tend to be the same length, they will take on a droning quality that will bore your readers to tears. If all of your sentences are short, your writing may take on a frenetic, fractured quality that will make your readers nervous.
The same statements apply to word choice. Use technical terms as sparingly as you can. Surround longer words with shorter ones, and vice versa. Watch out for industry jargon that will baffle the reader. Don't overuse your Thesaurus (no, it isn't on the list of references). While using a synonym or two can spice up your writing, using two different verbs to describe the same action can be confusing.
Stay off the Page
Generally speaking, a technical writer doesn't write in first person or refer to himself when writing documentation. Technical writing is generally best written in an informal, yet impersonal style, much the way this course is written. One exception to this would be a company blog. Blogs are usually written in first person and have a very informal tone. They are intended more as conversations, with readers invited to leave comments on each post. Technical writers who blog are free to inject more of their own personalities into their posts.
Use Active Verbs
It is better to say "push the button" than "the button is pushed." Using active verbs tends to make your copy stronger, clearer, and more readable, not to mention less wordy.Read Your Work Out Loud
When you have a section or a whole manual drafted, take the time to read it out loud, and note any passages that are difficult to articulate, or sound false to the ear. Pay attention to your rhythm. Is your writing lively without being too informal, or does it plod along like a Sherman tank? Are you overusing certain words? Are any sections too wordy to be clear? You can often find problems like these more easily by reading out loud than in your head. Any piece of writing can be improved when it is read over in this way.]]>