A good technical writer not only understands his/her intended audience, s/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
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.
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.
If you’re writing for clarity, above all else, it is important to use the same terminology over and over again. Avoid 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.
Use short active sentences
Traditionally, technical writers are told to always use short active sentences. This is good advice, but writers today are generally granted a bit more leeway than those of twenty years ago. Short active sentences still communicate instructions better than passive or long sentences – they leave less room for ambiguity or misinterpretation. However, some passivity and longer sentences are generally allowed within conceptual material (depending on your editor and group style rules).
In all cases, extraneous words should be removed. If your sentence makes sense without “the fact that” then delete that phrase. Extra words just give people more ways to misconstrue your meaning.
Use a consistent voice
Voice in writing is a nebulous thing. It’s difficult to quantify and can be even more difficult to control. Voice is essentially the tone of the writing. Most educational books are very formal and dry, often concerned with testing or expanding the vocabulary of those reading. Most fiction tries to be true to one character, picking up his or her mannerisms and attitudes and showing them on paper.
There is no one proper tone for documentation beyond the need for consistency. Readers may not specifically think about voice, but a sudden change from friendly to terse will be noticed and detract from the reader’s ability to focus on the information provided.
Many people feel a dry academic style works best while others prefer to be friendly and use simple language. Some types of documentation are best suited for a specific tone – introductory material generally works best with friendly inviting language and reference material is more geared toward short, terse language – but in general, it doesn’t matter what voice you use as long as it’s consistent.
Develop a consistent style
A lot of different elements combine to define a style for your writing. In general terms, a writer’s style encompasses things like voice, word choice, the use of formatting, and other similar elements. It’s the overall package.
When technical writers discuss style they generally concentrate on word choice and on the formatting and presentation of material – how different product elements are capitalized and typeset, how chapters are paginated, how indexes are formatted, and similar concerns. Most writing groups have their own style guides that cover that departments views on the spelling of certain ambiguous words (email vs. e-mail, for example). Often they select a particular book then add or change specific elements to suit their needs. The Microsoft Manual of Style for Technical Publications is the most popular choice, for good reason. It’s the most comprehensive guide I’ve seen. By starting with this (or another) book and just modifying its rules to suit your needs, technical writing departments can save a great deal of time and effort.
These customized sections (or full, independent style guides) should contain lists of product-specific words and their acceptable usage as well as departmental rules for comma usage, preferred choice when there are two acceptable spellings of a word, and your choices for capitalization, bolding, and italicizing. This last part is particularly important when documenting a programming language or tool – there are so many different elements in a language and your readers need to know, at a glance, whether you are discussing a function or a query (for example).
If you’re writing alone, you probably don’t need a formal style guide as long as you can be consistent. If you find yourself wavering, or if during the editing process you notice a lot of variation in word choice or formatting, then take the time to write a short personal style guide. Make sure you actually refer to it when writing – its mere existence will not add consistency to your writing.
Style guides and issues related to style can be among the most divisive in any writing group. Everyone has their own ideas on what is proper and right, and often those ideas conflict with each other. It’s almost certain that in any group situation you won’t like all of the decisions, but it’s important that you abide by them.
Maintain consistency in collaborative projects
It is especially important to maintain a consistent voice and style when more than one writer works on a single document. Readers should not be able to tell which parts of a book are written by one writer and which by another, or even that more than one writer worked on the book.
Minor deviations from the accepted style may not be noticeable in a book written by one person (as long as they are consistent) but if two or three different people each differ from the standard in different ways it will be noticeable and distracting to the reader.
One way to avoid such problems is to require each writer to read and edit those chapters or sections written by the other writers. If one of the other writers does something consistently different from the way you do it, it should be very easy to spot. Once these problem areas are identified you as a group can determine the best way to fix them and provide the needed consistency.