Technical Authoring

Apart from the obvious difficulty in understanding technical subject matter - the actual writing is not difficult if (as I do) you focus on the needs of the reader. When writing I ask the question 'Why will someone be reading this - what do they need to know?' educationists call this student centred.

This isn't 'Rocket Science' or some 'New Age' concept - in 1958 Morris Freedman gave a talk where he outlined his 'Seven Sins of Technical Writing'.

He began by saying:

'Technical writing cannot afford sloppiness of expression, confusion of meaning, or careless construction. Such writing hinders efficiency, wastes time, and may even cause damage.'

The following summarises his 'Seven Sins'.

Sin 1: Indifference (neglecting the reader)
Remember your audience. Don't use shortcuts of expression, sloppy organization, improper or inadequate labeling of graphic material, etc. Don't leave the reader hanging-you must help the reader to understand.
Sin 2: Fuzziness (vague words, meaningless words)
The military specializes in this sort of thing. For example, what does 'Anyone smoking in or around this mess hall will be dealt with accordingly' mean?
Sin 3: Emptiness (use of jargon and big words where 'normal' words could be used)
Don't try to seem important or impressive or use code language to show you are an insider: That is not your purpose. There is rarely any reason to say 'utilize' or 'utilization' rather than 'use,' or 'prior to' rather than 'before'.
Sin 4: Wordiness (an extension of Sin 3)
Some believe that if you can say anything with more words than necessary for the job, then by all means do so. For example, 'The front-mounted blade of the bulldozer is employed for earth moving operations on road construction jobs' could be reduced to: 'The bulldozer's front blade moves earth in road building.'
Sin 5: Bad Habits (the use of pat phrases, awkward expressions)
This sin can be interpreted as 'writing for the simple-minded.' Examples: 'red in color' equals 'red' - 'three in number' equals 'three' - 'square in shape' equals 'square'.
Sin 6: The Passive Voice (it takes the life out of writing)
Using the passive often makes reading matter more difficult to understand, to get through, and to retain. It creates difficulties where none exist. However, there are times when the passive is the only way to say something.
Sin 7: Mechanical Errors
While most technical writing is impeccable mechanically, there are some problems which do occur more often than others: Dangling participles and ambiguous references.

Dangling participles: 'Raising the temperature, the thermostat failed to function.' Who or what raised the temperature? Not the thermostat, which is what the sentence says.
Better: After I raised the temperature, the thermostat failed to function.

He ended by saying:

'Technical writing should be as clean, as functional, as inevitable as any modern machine designed to do a job well. This writing should be like good poetry-every word in its exact place for maximum effect, no word readily replaceable by another, not a word too many or too few, and the whole combination invisible, not calling attention to its structure, seemingly effortless, perfectly adapted to its subject.

However, good writing doesn't come without effort.'

Doesn't all of the above appear to be 'common sense'? Without reading a book or taking a course on Technical Writing anyone with common sense can do it. Just keep your audience in mind and try not to commit any of Freedman's 'Seven Sins'.