One big technique the best tech writers employ to produce sharp, crisp, short directions: they never use passive verbs.
Clear Instructions–for Everything
Tech writers write instructions and directions all day long. They write directions for people who work in tanning salons, for veterinarians who use tanks to give physical therapy to thoroughbreds, for engineers who operate huge robotics that put lipstick into tubes, or $3M machines as long as a basketball court that process wafers with chips.
When tech writers write to programmers, they tell them how to use HANA (high-performance analytical appliances), or Apache Cassandra (for database management); or Hadoop, which stores, processes, and analyzes data. No matter the audience, we always write instructions and directions.
Good Instructions vs. Bad Instructions
If a server fails at 2:00 A.M. in a data center, a Programmer must look up troubleshooting in the documentation. If the server belongs to VISA, merchants do not get the money for purchases made. Also, he may have a new baby at home who won’t stop crying and his wife wants him there.
So which direction below helps him? A. or B.?
A. When replicating database information, it is important to note that each version must be able to communicate with the other for information which is (Passive: has killer BEs)
B. Look at recent database errors. Make sure the current version of the database still accesses all information in the previous version (Active. No killer BEs)
How to Spot the Killer BEs (Passive Verbs)
A writer wrote instruction A., above, with the passive “to be” verbs is and be. Best-of-breed, top-flight tech writers never use any of the following words, the six Killer BEs:
When any of the above six words sneak into a sentence, that sentence totally lacks any Actor, or Subject, or Doer. Thus, the reader does not know if he or she takes an action, or if the machine or software does the task for them. For another example,
A. The system will be backed up.
B. Back up your workstation every night.
Sentence A. has a killer BE word; the second sentence does not.
When you write using passive voice, you get a sentence like this, from an article about poisonous water in Flint, Michigan:
Necessary actions were not taken as quickly as they should have been.
Great. No person had the responsibility of taking any action, so we have no bureaucrat to blame.
Technical Writing: the Craft of 1,000 Knives
Along with never using a passive “to be” word, good technical writers strive to cut down the number of words in their directions.
Guess what? Eliminating the killer BEs cuts your word count way down. In their weakness, killer BEs need so-called helping verbs, with constructs such as will be processed, has been determined, will have been installed.
If you must know, the best technical writers do not use the dreaded will word, either. They put everything in present tense. Programs compile, not will compile. Dialogue boxes appear, not will appear.
We keep everything very terse, direct, and accurate, only writing up tasks a particular reader wants to do, and numbered steps for doing it. End users do not care about technology `under the hood` of the car. They just want to start the ignition and go.
Philosophers Write about This
Linguists, philosophers, and psychiatrists encourage us to avoid using the passive verbs. They don’t like these words because they keep us from drilling down and getting specific. They call their movement of avoiding the killer BEs E-Prime, and list as some of the benefits: lively, concise writing and speaking; clearer, more critical thinking; better communication, evaluation, and decision-making.
A Difficult Discipline, But You Can Do It
It takes some effort and practice, but you can write more authoritative, stronger, more-convincing emails, reports, employee reviews, PowerPoint slides, bids and proposals if you never use any of the killer BEs.
Try it. You may get a promotion.