One approach to teaching technical writing is to teach the common pieces a writer might be asked to write: the proposal, business letters, technical reports, abstracts. The following tips have to do with making your writing clearer, whether you are writing a business letter, a software manual, or a grant proposal.
Get More Mileage out of Headings
It's hard to imagine tackling a writing project without breaking it down into separate parts. Most pieces longer than a page or so will be divided into several sections, each with a different heading. Creating headings is straightforward, isn't it? Maybe, but I frequently see documents that could be improved by improving their headings.
A good heading is a topic phrase that summarizes the section. Readers skimming the writing will have an easier time if your headings accurately express the topics contained in each section of the document.
Some books warn against complete sentences with subject and verb. You'll have best luck with a sentence fragment that is clearly a topic. Prepositional phrases can occasionally be used if they express a topic, but usually aren't necessary. You may see a heading such as "About cleaning the Motor." This might be better as written as "Cleaning the Motor."
Along these same lines, headings should stand alone, and the content should too. Sometimes in an effort not to be repetitive, writers write a passage like this (from a software manual):
Heading: Opening a file
Paragraph: "To do this, pick Open from the File menu.
Here, the antecedent of 'this' is in the heading. This requires the reader to read the heading to understand what the paragraph is about. If a skimming reader skips over the heading, he or she is lost. A better approach is:
Heading: Opening a File (Or "How to Open a File")
Paragraph: To open a file, choose Open from the File menu...
By the way, to be sure headings contain topics that are representative of section content, check the headings again after you've completed the first draft of a document. In the writing, sections have a way of taking on a life of their own, and a hastily composed heading may no longer be on target.
Of course the latter problem would be taken care by a good editor (if you have that luxury), but frequently the first heading that you write can end up in the final version if you are not careful.
Use Present Tense
Technical writing books often present procedure writing (a series of numbered steps) for a garden-variety example of technical writing. When doing this type of writing, present tense gives immediacy to describing the process or procedure.
Often, the cause and effect nature of a process tempts authors to use future tense. For example, a software manual might contain sentences like this:
"Choose Print from the menu and the Print dialog box will appear."
Rephrased with the present tense this sentence appears:
"Choose Print from the menu and the Print dialog box appears."
or, if you prefer:
"Choose Print from the menu and the Print dialog box displays,"
By the way, it is natural and desirable to use future tense when an action really will be delayed a period of time--really will happen in the future:
"Choose Print from the File menu and 20 pages will be printed to your printer, after they are first spooled to the print spooler.
I think the tendency to want to be scrupulously accurate about causation (this happens first, then that happens next) encourages writers to use future tense. Will a reader misunderstand the order of events in your technical prose when you use the present tense? I don't think so. In fact, when a person is reading quickly, the present tense is easier to understand since it enables the reader to skim along at a good pace.
And, if you are consistent with tenses (and everything else about your writing), the reader begins to trust where you are going and will have no trouble filling in the blanks.
Decide Who is the Actor in the Sentence
Experts warn about revising your prose to remove the passive voice. But not all vague, murky prose derives from using the passive voice. It's sometimes more important to decide who is the actor in a sentence. Sentences are bolder when a bold actor performs a bold action.
And this brings up a question? When writing about technology, computers, or a scientific process or principle, who is the actor? Sometimes it’s hard to tell; or the actor is an inanimate object.
When writing instructions, you may refer to the reader in the imperative: [you] assemble this piece, [you] push the button. This places the sentence in the active voice, and the use of "you" – rather than the more distant "one" – is acceptable, even in vogue.
But, when writing about software, sometimes the best actor is the software program itself. This is called anthropomorphizing the program and people have told me it’s bad. For example, you have a software product called, Project -X. Say:
"Project X opens a dialog and displays your data."
Rather than:
"You will be asked which file to open and your data will then be displayed."
(The latter sentence combines the future tense with the passive voice!)
I said that not all murky prose was in the passive voice. Note that sometimes you can even put a sentence in passive voice and have it will still emerge forth into the light of day. If you don’t obscure the actor. For example:
"The file is opened by Project-X."
Follow a Task-based Approach
When doing technical writing you are confronted with a mass of detail. If you're documenting how to shut down a nuclear reactor, there are many details to get down on paper (and accurately)! Many technical writers find themselves writing about computer software or hardware. The same thing applies.
You know you need to be organized (don't you?). The first organization that suggests itself is to break the system up into its parts. That is, for a nuclear reactor, or lawn mower--describe the parts: the motor and its parts, the handle, the blade that cuts the grass. For a software program you describe the interface: the menus, the screens, the messages displayed by the system.
Consider this! People use the product you are writing about; that's why they are reading your document. So, when writing a "user manual" for a lawn mower you focus on how to start the mower, mow the lawn, how to stop the mower. For a software program you focus on how to install, start the software, create a new document, print a document, work with a document, save it and so on. The structural approach for the same task is:
"The File menu item is located next to the Edit menu and it contains the options New Save, and Save As."
A structural organization of technical material is not "wrong." In fact, you have to include such information if your document is to be complete. It is, however, wise to study how the user will use the information you are providing. A software user wants to accomplish a task first of all, and find out about 'neat features,' bells and whistles, later.
That is, a task-based approach will affect the overall structure of your document. Once you establish some tasks first, you might put easier and more common ones first followed by less-used tasks or features. You may find yourself weaving structural material into the text, or grouping it in a later reference-style section. You can move less-frequently used features to the back.
By the way, the structural approach is a natural one for engineers. Why? Because it describes a product or process from an engineering perspective (like a schematic or a structure chart in software).
To summarize, what tasks does the reader of your material want to perform? Think about it. It ain’t easy. But, with effort you can come up with at least the most obvious tasks you must document. Put those in first, then continue. Your user document will benefit in terms of organization, readability and usability.
Thinking is Writing, Writing is Thinking.
When considering (or estimating) the total effort involved in a writing project, don't overlook the work done analyzing the problem.
In fields less technical such as fiction and journalism it's recognized that the down time spent away from the keyboard (or pen and paper) is important. James Thurber, famous writer, journalist, humorist, and New Yorker staffer, was asked when it was that he wrote: "I have a hard time telling when I'm not writing," he is supposed to have said. [paraphrasing.]
The down time of technical writing may be less unconscious (though I'm not so sure the unconscious doesn't play a role here too). It is when you are analyzing the product, process, and procedure to be documented. You need this time to understand what you are writing about.
In organizations with staff technical writers, writers may have access to people who are expert in the subject being documented. These people may be the creators or designers of the system in question. Sometimes known as Subject Matter Experts (SMEs), these people are crucial to establishing what needs to be communicated.
Today, technical writers (often called technical communicators) thinks of themselves as advocates for the user. That is, they explain the system clearly from the user's perspective. In some situations, technical writers even suggest changes to the system or procedure while it's being created. Since they are analyzing everything from the user's perspective, they are uniquely able to make such suggestions.
Of course, whether their suggestions are accepted depend upon the personalities and politics of the organization, and upon the technical feasibility of the suggestions. But success here, as well as generally, depends on the ability of the technical communicator to communicate. These five tips may help.
Doug Nickerson is the author of 'Official Netscape javabeans Developer's Guide (Ventana, 1997). Presently he is working on his third dozen of articles for the computer-oriented press, such as Dr. Dobb's Journal, C/C++ User's Journal, Auerbach Press and Computer Bits. Doug lives on Cape Cod with his wife and two small sons, and can be reached at: