Technical Writing: Clarity and Precision

Good writing is clear and precise. Good technical writing, to borrow a phrase from the young people, is totally clear and precise. Let’s be real: most people don’t bother reading technical documentation until they’re stuck and don’t know how to proceed. Enter this? Press that? “What do I do now?” Unfortunately for those sorry folks, their foray into the user manual or online help is often not a good experience. The reason: the explanation is not clear and/or precise. Such is the state of my chosen profession.

Let’s consider the following sentence from a draft version of a manual we are writing for help desk support people: “Most updates are removing charge types after deactivation of a service.” The first time I read the sentence, I scratched my head and wondered what the writer was trying to say. I had a vague notion of the message but only because I’ve been involved with the project for several months and already knew what the write was trying to say. However, the support person, on the phone with a merchant with a problem – and probably not a very happy merchant either – might have some serious confusion about what he’s supposed to do or when he’s supposed to do it.

The writer and I discussed the point she was trying to make about charge types and deactivations and arrived at the following solution: “The most common update after deactivating a service is removing charge types.” A pretty clear and precise explanation, I thought. But she did one better, “The most common update that requires a request to the XX department is removing charge types after deactivating a service.” Even better, I saw, because it included a vital piece of information the support person should know – that this particular type of update that we’re describing is one in which the support desk sends a request to a specific department. In other words, it’s not every or even any update: it’s a specific kind of update. Was the specificity and clarity worth the time we spent? Good question. I’d suggest you ask the support person who has to deactivate the service.

The other technique lazy writers use to avoid having to fully explain or understand what they’re trying to say is the passive voice. The University of North Carolina Writing Center presents it this way: “Use of the passive voice is not a grammatical error. It’s a stylistic issue that pertains to clarity—that is, there are times when using the passive voice can prevent a reader from understanding what you mean.” (http://writingcenter.unc.edu/handouts/passive-voice/)

Why a technical writer would want to go to the trouble of writing something that prevented a reader from understanding what he was trying to explain is a good question. Certainly, as the Capital Community College Foundation says, “We find an overabundance of the passive voice in sentences created by self-protective business interests, magniloquent educators, and bombastic military writers (who must get weary of this accusation), who use the passive voice to avoid responsibility for actions taken.” (http://grammar.ccc.commnet.edu/grammar/passive.htm)

True enough. But it may also be much simpler than that: the person doesn’t know who does what and doesn’t want to take the trouble to find out.

It is only through clear and precise sentences that a technical writer can hope to translate difficult and, at times, truly esoteric technical concepts. It’s not easy and it’s not quick. It takes time because the writer has to first completely understand the topic and then, and only then, write about it. The results, however, when done properly, are worth the investment.