Lesson 3: The Importance of Word Choice and Consistent Writing
A good technical writer not only understands his intended audience, he understands the importance of clear and concise writing. Although most writers dream of beautiful prose that can move readers to another plane of existence, technical writing is all about removing any possible ambiguities so the reader understands precisely what to do. Short descriptive active sentences are generally better than long flowery lines filled with metaphor. Word choice is paramount to a technical writer. If there is any possible way an instruction can be misread or misconstrued someone will do so. When possible consequences of wrong actions are data corruption and data loss it becomes very important that users understand what you are telling them to do.
Consistency is also important. If you lead your users to expect all functions to appear in boldface followed by a set of parentheses, then make sure all functions appear that way. Otherwise, your readers may not realize that they're all functions and could get confused. Similarly, keep a similar style and vocabulary throughout each document. If you're writing an introduction filled with very general and basic conceptual material make sure you avoid as much technical terminology as possible and that you always define all terminology you do use. If several writers are collaborating on the same document make sure that individual voice doesn't shine through. When the document is finished you should not be able to tell where one person stopped and another picked up. You shouldn't even be able to tell that more than one person worked on the document.
Exercise proper word choice
I often find myself muttering the famous line from The Princess Bride as I read books: "I do not think that word means what you think it means". Many writers have at least a minor problem with misused homonyms - using "their" when they mean "they're" or using "it's" instead of "its". It's important to have a good general grounding in language and grammar to avoid these errors.
There are a lot of other problematic words that sound similar but have very different meanings. Selecting the incorrect one can really confuse your users.
These are common pitfalls that befall most writers. Beyond general proper word choice, technical writers must be sure to develop a very precise vocabulary specific to the product or projects they're working on. There are many terms and names that have commonly been adapted by the computer industry; you must learn these conventions and use them properly so that readers can apply their previous knowledge to your books. If a particular type of GUI screen element is typically called a widget and you call it a whamboozle, not only do you not get instant recognition from people who know what a widget is, you could lead them to believe your whamboozle is not a widget (for otherwise you surely would have called it a widget).
Most of us are taught in school to look for alternate ways of saying the same thing when we write. Unfortunately part of being a technical writer is unlearning habits our English teachers drilled into us for years. Technical writing exists solely to convey information. It is not meant to be pretty writing, writing that makes you sigh with pleasure just from the reading. It isn't generally meant to make the reader think about a host of ideas, sorting through their own views on controversial or confusing topics. Many of the constructs used in other types of writing simply aren't appropriate when you're writing documentation. Remember all those lessons regarding metaphors and simile? Purge them from your brain.
If you're writing for clarity above all else it is important to use the same terminology over and over again. If you refer to a particular nameless part of your product as a wombeezil make sure you use that term over and over again rather than trying to come up with fancy terms and descriptions solely for the sake of adding variety to your writing.
There are entire books devoted to defining common computer terminology and common usage of terminology in documentation; I cannot go into all of even the most common issues here. I strongly recommend referring to the Microsoft Manual of Style for Technical Publications for more information on this and other style concerns. Unfortunately, the book is currently out of print so you may have so difficulty locating a copy.
