Technical Writing – Anticipate Resistance. Eliminate it in Advance.

©  2010 Ugur Akinci
Technical writing shares one very important structural feature with copy writing: anticipation of resistance.
To write a good technical manual, you have to anticipate why the reader might doubt the veracity of your instructions; why they might resist it. Then, like a skilled bomb-removal expert, you have to defuse and remove that resistance by explaining the exact reason why you’re asking them to do a certain thing in a certain way.
If you do not provide the WHY behind the HOW, you may lose your readers in mid-stream. The readers of the 21st century are an educated, smart and experienced bunch. They expect and deserve nothing less.
Here is an example:
“Purge the Projects database (Proj_DB) before refunding unused funds to the Contractors.”
This can be improved by describing HOW to purge the database:
“Purge the Projects database (Proj_DB) by selecting Database > Purge > Projects option from the main menu before refunding unused funds to the Contractors.”
But, this does not address the resistance most readers would feel: “Why should I do that? What if I don’t purge the database first?”
You can take care of the anticipated resistance by also providing not only the HOW but also the WHY of the procedure:
“Purge the Projects database (Proj_DB file) by selecting Database > Purge > Projects option from the main menu before refunding unused funds to the Contractors. Refunding unused funds without purging the Proj_DB file results in data leakage and corruption of all member records across all sites.”
Now your reader will realize the severe consequence of not purging the said file, be more careful to follow your procedural steps and try harder to do it the right way. Explaining the WHY of a recommended action always increases team harmony and productivity.