It’s important in technical documentation to be clear about who does what. It’s also important in news reporting. One of my pet peeves is this kind of headline from the Montreal Gazette:
The headline is ambiguous; but this is the first article about the crime, so you can read the first paragraph to find out that the police were the ones who fired carelessly into a public street and killed someone who was merely walking to work.
In later articles, the phrase “police shooting” will appear again and it will be harder to find out if the crime is shooting of police or by police. This kind of writing should be outlawed!
If you’re writing to be understood, one of your most powerful techniques is to put one idea into each sentence. Here’s an overstuffed sentence explaining how stalagmites in caves can be used to calculate the ages of the caves and more. The introductory fact is, “Like trees, stalagmite contain seasonal growth lines, which vary in thickness according to the amount of water available.” But then comes this information overload:
The oxygen and carbon isotope ratios locked into the crystalline structure of calcites in each growth line also provide evidence for the prevalent temperature and the proportion of trees versus grasses in the local environment, respectively.
“Respectively” tells the reader, “You sort it out.” Here’s what I’d rather read:
Each growth line represents a year. The isotope ratios in the calcite crystal structure tell us more about that year. Oxygen isotopes (O16:O18) show the temperature. Carbon isotopes (C13:C14) show the proportion of trees to grasses in the local environment.
If you want someone to read and understand, sort out the ideas and make them flow.
Sometimes, writers insert useful but parenthetical information into an otherwise straightforward flow of thought.
[Our company] requires the services of a skilled systems professional, with strong technical writing experience with user manuals and online help in a ZippyWrite* environment, to assist one of our clients on a contract basis.
The problem with that is that the reader must hold in mind the first part of the sentence, process and store the middle, and then splice the first part to the final part. It’s like holding your breath: the longer it takes, the worse it feels. So let’s do the work for the reader and give them two complete thoughts:
[Our company] requires the services of a skilled systems professional on a contract basis to assist one of our clients. We are looking for someone who has strong technical-writing experience with user manuals and online help in a ZippyWrite* environment.
We can even remove some of the vaguer terms and replace them with specifics:
[Our company] requires a skilled technical writer on contract, to assist one of our clients. The writer must have strong experience writing both user manuals and online help in a ZippyWrite* environment.
*Name obfuscated to avoid mentioning a real product
Here’s a sentence from a job ad:
The successful candidate must be available to commence the duties of this position as soon as the selection process has been made.
I prefer the usual form:
You must be able to start immediately.
I just came upon this: “The instructor is NOT required to have course wear.”
I think that the writer meant, “We supply the instructor with courseware.”
Anne Gentle is our guide to how to use Twitter and other social media for the necessary marketing of a freelancer and, more intriguingly, for technical documentation. Read “Focus on Twitter for Technical Documentation.”