Technical writing fails when it attempts to become “fine writing” or “creative writing.” Why? Because one of the main tools of “fine writing” is attributing human qualities to non-human actors and agents. That is a definite taboo in technical documentation.

For example, you make that mistake every time you type a sentence like “When the system notices a user selection, it changes channels.”

“Consciousness” is an attribute of organic consciousness (human, animal, or perhaps even plant). Machines and computer systems are not “aware” of anything in the way that humans are aware of things.

A better phrase would be: “When the system detects a user selection, it changes channels.” It is not claimed here that the “system” is “alive” with “consciousness.”

The same “fine writing” mistake is made when a technical writer uses adjectives, superlatives, and draws an exaggerated picture of technical states and processes.

For example, in a novel, it may be in keeping with “poetic license” to speak of a “beautiful red pomegranate-colored pilot light” that comes on when the user presses the off button. But in a whitepaper such an exaggerated description is ridiculous.

A better description would be a “red pilot light comes on when the user presses the OFF button”. It is simple, correct and effective.

Again: “When you hear an awful sound coming from module B, it’s time to change the oil.” The adjective “horrible” does not belong to technical writing as its meaning is subjective and can change from one person to another. A whitepaper should be as objective as possible to eliminate any variation in the application.

A better phrase would be: “When you hear a high-pitched sound coming from module B, it’s time to change the oil.”

Leave a Reply

Your email address will not be published. Required fields are marked *