Five Tips to Improve Your Technical Writing Books on technical writing contain guidelines on how to write specific technical pieces: proposals, formal reports, abstracts, business letters. The five writing tips below will improve your writing no matter what type of technical writing you do. I. Get More Mileage out of Your Headings It's hard to […]
Five Tips to Improve Your Technical Writing
Books on technical writing contain guidelines on how to write specific technical pieces: proposals, formal reports, abstracts, business letters. The five writing tips below will improve your writing no matter what type of technical writing you do.
I. Get More Mileage out of Your Headings
It's hard to imagine tackling a writing project without breaking it down into separate parts. Most documents longer than a page or two will be divided into several sections, each with a different heading. Creating headings for these sections should be straightforward, but I frequently see documents with headings that could use improvement. Many of these documents are my own!
A heading should be a phrase that clearly summarizes a section. If you've worked upon your material until each paragraph and section has a clear topic or point, you should have no trouble creating a short phrase that accurately conveys this topic information.
Supplying a heading that relates well to the content has many benefits. For example, a reader is better able to skim your material, skipping sections that are not of immediate interest.
One problem I've seen in business and manual writing is headings that are too closely interrelated with the text. In an attempt to avoid repetition, writers write the following (from a software manual):
Opening a file
"To do this, pick Open from the File menu."
In this example, you must read the heading and the paragraph together or you are lost. In grammatical terms, the antecedent of the pronoun "this," is in the heading. The text of the paragraph depends upon the heading. A better approach is the following:
Opening a File (Or: "How to Open a File")
"To open a file, click the File menu and select Open."
In general, don't be afraid to repeat yourself in technical writing. Repetition helps your reader establish the context of the material, especially when the content is unfamiliar.
Another problem with headings might be called "topic drift." When writing a first draft, I frequently block out individual sections as they seem to fit, and compose a heading for each on the fly. In later drafts, sections have a way of taking on a life of their own, and a hastily-composed heading may no longer be on target.
To combat this, I check headings again after I've completed the first few drafts of a document. While writing a computer book, I found that the development editor excelled in catching inconsistencies between section headings and the text. Even if you do have the luxury of an astute editor, it's still your responsibility as author to go to great lengths not to confuse the reader!
Which makes me wonder, is "Get More Mileage out of Your Headings" really a good title for this section? How about, "Keep Your Headings on Target"?
II. Use Present Tense
Present tense brings clarity and immediacy to describing a process or procedure. The cause and effect nature of procedure writing tempts many writers to use future tense, however. For example, a software manual may contain sentences such as:
"Click the File Menu, and select Print. The Print dialog box will be displayed."
"Click the File menu, and select Print. The Print dialog box displays."
True, it's natural (and often necessary) to use future tense when an action really is delayed a period of time, that is, really happens in the future:
"Click Print and the 20 pages are sent to the print spooler, and will be printed in full color."
Why do writers mix up their tenses in technical writing, sometimes using future and past in the same sentence? One answer is that it's astonishingly easy to do. Writing only in present tense, when appropriate, is much harder.
Writers also use future tense to be very accurate when conveying causation (first this happens, then that happens).
I find that keeping your text in the present tense usually does not confuse the reader. In fact, the present tense is often easier to understand and enables the reader to skim along at a good pace. An added benefit: if you're consistent with tenses, the reader begins to trust your writing and your approach-and may even fill in the blanks in your prose where necessary (though this should never be necessary!).
III. Identify the Actors in Your Sentences
Experts warn you to eradicate the passive voice from your writing. Not all vague and lifeless prose derives from using the passive voice, however. It's sometimes more important to identify the actor in each sentence.
Deciding who is performing the action, then placing this actor in the subject location, leads to clearer writing. This advice, given by Joseph Williams1, seems especially relevant to technical writing.
But when writing about technology, computers, or science, how do you identify the actor? It can take some thought, since on many occasions the only available actor is an inanimate object. For instance, when writing about a software system, sometimes the best actor is the software system itself. Suppose you have a software program called Project-X and you write this:
"You are asked which file to open and your data will be graphed."
"Project-X displays a file open dialog and graphs your data."
The opening of a file leads to disk access.
Whenever Project-X opens a file, it accesses the disk.
As an aside, referring to a software program this way is sometimes called anthropomorphizing-you make the program appear almost human. Some people feel that anthropomorphizing a computer program is a bad practice. I think such an approach is fine as long as you don't talk about its thoughts and feelings!
Here's another idea. When writing instructions, urging the reader to perform some action, make the reader the actor in the sentence. The pronoun "you" will usually be implicit, as in the following:
1. Assemble the top of the gas grill, following the steps in figure
2. Attach the top to the bottom using the four wing nuts.
This approach gives you a clear actor (the reader), performing an action (assembling, attaching). It places the sentence firmly in the active voice too. Of course, an editor or a company/publisher style guide might abhor addressing the reader directly, so always check your local guidelines first.
To summarize, sentences are bolder when a bold actor performs a bold action.
IV. Follow a Task-based Approach
When doing technical writing, you are often 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 today find themselves writing about computer software or hardware. The same thing applies.
When documenting a system, the first organization that suggests itself is to break a system up into its parts. When writing about a lawn mower, you describe the parts: the motor, its subassemblies, the spark plug, the adjustable handle, the blade. For a software system you describe the interface: menus, screens, and the messages or reports produced by the system.
But consider this: readers are reading your document in order to accomplish something. So, when writing a user manual for a lawn mower it's best to focus on how to start the mower, mow the lawn, and stop the mower.
For a software system, you describe how to install, start the software, create a new document, print a document, work with a document and save it, and how to shut down the system when you're done. The structural approach, on the other hand, leads to sentences such as:
"The File menu (to the left of the Edit menu), contains the options New Document, Save, and Save As, Print, and Exit"
A structural organization of technical material is not "wrong." In fact, you have to include structural information if your document is to be complete. It is, however, prudent to study how your information will be used. A software user (or a person mowing a lawn) wants first of all to accomplish a task, and find out about bells and whistles later.
A task-based approach also affects the overall structure of your document. One approach is to identify common tasks, place these first, followed by less-used tasks or features. The structural material can be woven into the main text, or grouped it in a later reference-style section.
What tasks does the reader of your document want to perform? This analysis is difficult, but with effort you can come up with at least the most obvious tasks you must document. Put those in first, then continue. Your writing will benefit in terms of organization, readability and usability.
V. Thinking Is Writing Too
When considering (and estimating) the total effort involved in a writing project, don't overlook the work done to analyze your topic.
In creative writing it's recognized that the down time spent away from the keyboard (or pen and paper) is important. James Thurber, journalist, novelist, 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.
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). During your down time, you analyze 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. They may be the creators or designers of the system being written about. Sometimes known as Subject Matter Experts (SMEs), these people are crucial to establishing what needs to be communicated.
Today, technical writers often call themselves technical communicators and think of themselves as "advocates" for the user. That is, they explain a system clearly from the user's perspective, anticipating the questions and problems of an average user.
In some situations, technical writers may suggest changes to the system or procedure while it's being designed. Constantly thinking about the user's perspective makes them uniquely able to make such suggestions.
In my experience, whether their suggestions are accepted depends 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.
1. Williams, Joseph M., Style: Toward Clarity and Grace, University of Chicago Press, 1990