At its core, good technical writing is simply good writing about technical topics. If you are approaching this field from a writing background, you may already know the basics of good writing but need to learn more about the technology. If you are an engineer or developer, perhaps you haven't exercised your writing muscles in awhile. Here are some general guidelines for producing clear, understandable, readable writing that will help your readers gain the information that they need.
| Clarity and Simplicity |
Write like You Talk
Sometimes people think that written communication should not resemble spoken communication. If you're taking the trouble to write it down, the thinking goes, shouldn't it be more formal, more serious? In a word, no, especially when you are working to explain complex subjects in an understandable way. Good, clear writing is a lot like talking, but without the pauses, Ums, ahs, and "ya knows." In fact, if you prefer face to face communication to writing, you may prefer to do your writing with your voice and a voice recorder, dictating the points you would like to get across, and then transcribing and editing them later. Plenty of accomplished writers work this way.
Get Straight to the Point
If you're writing the section of the user's manual that tells the user how to turn the product on, show the user a picture of the on/off button, note in the text where the button can be found, and then write "Turn the power button on." The user doesn't need to know that turning on the power button closes an electrical circuit, causing current to flow. They don't need to hear that the original design called for the button to be on the right side and now it is on the left. They do not need any information on the history of power button design. They simply need to know where the button is and what it does. This example may sound facetious, but it is good to remember the user's needs when writing documentation. If your content doesn't help the user operate the product, then you aren't doing your job.
In print manuals, space is often limited by the constraints of the printing process and the cost of paper, so excess verbiage is kept out of manuals for cost reasons as well as for editorial ones. With more and more help online now, the demands of space are theoretically eliminated, since web pages can be almost infinitely long. But it is more important than ever to get straight to the point. Readers on the Web tend to skim, hoping to find the information they need quickly and then move on. If you can answer their questions in the first paragraph of your help file, then their needs will have been served and you've done your job well. Always think of your user, and remember to respect his or her time.
Simplify
One of the challenges of technical writing is to simplify complex topics without oversimplifying. This is where putting yourself in the user's place can be helpful. How much does the user need to know about this aspect of the product's operation? Are you giving him enough information without overwhelming him? When in doubt, it is probably better to err on the side of simplicity. One method of simplifying complex topics, and of helping users relate to a new piece of equipment or software, is by drawing an analogy to something that they are more familiar with. Instructors explaining the flow of electricity often draw comparisons with the flow of water through pipes. Technicians explaining machine maintenance often compare their machines to cars, which nearly everyone knows something about operating and maintaining.
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.
| 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. 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.
Interested in learning more? Why not take an online Technical Writing course?
