5.  Grammar Concerns for Tech Writing.     

Passive Voice: 

Like hearing finger nails on a blackboard, the passive voice is guaranteed to make English teachers cringe.  Using the passive voice is not wrong, but it is somewhat unnatural, because spoken English almost always uses the active voice.  The natural syntax or word order for spoken English is: subject, verb, object.  The passive voice begins with the object and often dispenses with the subject, leaving the agent who performs an action implied. 

Know when you are using the passive voice.  Use the grammar checker with MS Word.  Click on sentences underlined in green.  Word will suggest how to change passive constructions into the active voice.  Use the passive voice to describe actions in which the agent is:

• Unknown
• Arbitrary
• Unimportant

The problem is that this list seems to cover almost all technical writing occasions.  Some writers defend the passive voice when they are criticized for using it.  They say it is the norm for the kind of writing they do, or their boss or editor demands it.  See how well you like in these examples:

Psalm 23: 

1.  King James Version: 

The Lord is my shepherd; I shall not want.  He maketh me to lie down in 
green pastures: he leadeth me beside the still waters.  He restoreth my soul: 
he leadeth me in the paths of righteousness for his name's sake.  Yea, though 
I walk through the valley of the shadow of death, I will fear no evil: for thou 
art with me; thy rod and thy staff they comfort me.  Thou preparest a table 
before me in the presence of mine enemies: thou anointest my head with oil; 
my cup runneth over.  Surely goodness and mercy shall follow me all the 
days of my life: and I will dwell in the house of the Lord forever.

2.  Passive Version: 

The Lord has been designated as my shepherd; nothing shall be wanted by 
me.  I am made to lie down in green pastures by him: I am led beside still 
waters by him.  My soul is restored by him; I am led in the paths of righteousness 
for his name's sake.  Yea, though the valley of the shadow of death is walked 
through by me, no evil will be feared by me; for I am accompanied by thee; I will 
be comforted by thy rod and thy staff.  A table is prepared by thee in the 
presence of mine enemies: my head is anointed with oil by thee; my cup is made 
to run over.  Surely I will be followed by goodness and mercy all the days of my 
life: and the house of the Lord will be dwelled in by me forever.

3.  Passive Version Avoiding First-person Pronouns:

It has been designated that the Lord is the shepherd for his followers; nothing 
shall be wanted by those  followers.  They are made to lie down in green 
pastures by him: they are led in the paths of righteousness for his name's sake.  
Yea, though the valley of the shadow of death is walked through by them, no 
evil will be feared by them; they will be comforted by his rod and his staff.  A 
table has been prepared by thee in the presence of the enemies of thy followers: 
their heads are anointed with oil by thee; their cups are made to run over.  
Surely thy followers will be followed by goodness and mercy all the days of 
their lives; and the house of the Lord will be dwelled in by them forever. 

4.  Passive Version Avoiding Personal References:

It has been designated that the Lord is the shepherd for his followers; nothing 
shall be wanted.  Made to lie down in green pastures: paths of righteousness 
are followed for his name's sake.  Yea, though the valley of the shadow of 
death is walked through, no evil will be feared; comfort will be found in the 
rod and staff.  A table has been prepared in the presence of the enemies of 
the followers: heads are anointed with oil; cups are made to run over.  
Followers will be followed by goodness and mercy all the days of life; and 
the house of the Lord will be dwelled in forever. 

5.  Jerusalem Bible Version: 

Yahweh is my shepherd, I lack nothing.
In meadows of green grass he lets me lie.
To the waters of repose he leads me; there he revives my soul.
He guides me by paths of virtue for the sake of his name.
Though I pass through a gloomy valley, I fear no harm; beside me your rod 
and your staff are there, to hearten me.
You prepare a table before me under the eyes of my enemies; you anoint my 
head with oil, my cup brims over.
Ah, how goodness and kindness pursue me, every day of my life; my home, 
the house of Yahweh, as long as I live!

* * *

Notice the use of second-person pronoun ("you") in the Jerusalem version.  The second-person point of view is "user friendly" creating a desirable informal diction level.  A rather surprising choice in the Old Testament: to suggest that the reader is the focal point rather than Yahweh!

Here is the kind of notice your insurance company probably sends you:

Cancellation 
This policy may be canceled by the Named Insured by surrender thereof 
to the Company or any of its authorized agents, or by mailing to the Company 
written notice stating when thereafter such cancellation shall be effective.  
This policy may be canceled by the Company by mailing to the Named Insured 
at the address shown in this Policy written notice stating when, not less than 
thirty (30) days thereafter, such cancellation shall be effective.  The mailing of 
notice as aforesaid shall be sufficient notice and the effective date of cancellation 
stated in the notice shall become the end of the policy period.  Delivery of such 
written notice either by the Named Insured or by the Company shall be equivalent 
to mailing.  If the Named Insured cancels, earned premium shall be computed in 
accordance with the customary short rate table and procedure.  If the Company 
cancels, earned premium shall be computed pro rata.  Premium adjustment may 
be made at the time cancellation is effected or as soon as practicable thereafter.  
The check of the Company or its representative, mailed or delivered, shall be 
sufficient tender of any refund due the Named Insured.  If this contract insures 
more than one Named Insured, cancellation may be effected by the first of such 
Named Insureds for the account of all the Named Insureds; notice of cancellation 
by the Company to such first Named Insured shall be deemed notice to all Insureds 
and payment of any unearned premium to such first Named Insured shall be for the 
account of all interests therein.

Does anyone read these things?  Isn't part of the purpose of such prose to allow the agency to claim that it has informed customers of the terms of an agreement, but avoid really doing so?  What if you received this revision? 

Can This Policy Be Canceled? 
Yes.  Either by you or by us.  If you wish to cancel your policy, mail us or our 
authorized agent (the agent or office that sold you the policy) a notice.  You can 
also stop-by your authorized agent's office to sign a paper telling us to cancel your 
policy.  If you wish to cancel your policy at some date in the future, mail us a notice 
indicating the date when you want the policy to stop.  We will mail you a refund of 
your overpayment, determined by a "short rate table," which calculates a per day 
rate and service charge.
If we cancel your policy, we will mail or deliver to you a cancellation notice effective 
at least 30 days after you receive the notice.  Of course we will also send you a 
check for unearned premium, figured at the per day rate.

Most states now require insurance companies to write policies in "plain language" rather than legalese.  

Still not convinced?  Compare these two versions of a baseball story.

The next man up was Swenson.  His bat was nervously held on his shoulder.  
Two strikes and a ball were thrown. The crowd was tense with hope.  The 
fourth pitch was delivered by Cox.  Even while the ball was in mid-air, there 
was a feeling of expectation among the fans.  The ball was hit squarely by 
Swenson.  The ball was lifted high into left field.  It was Swenson's tenth homer.

* * *

Next, Swenson trotted up to the plate.  He nervously shouldered his bat. 
Two strikes and a ball whizzed by him.  The tense crowd buzzed with hope.  
Cox hurled his fourth pitch.  Even while the ball hung in mid-air, expectation 
shivered through the fans.  Swenson squared into the pitch.  The ball climbed  
high over left field, then nose-dived into the stands.  Swenson had hammered  
his tenth homer.

First-Person Point of View: 

Many writers use passive voice because they have read innumerable reports and scientific articles written from the third-person point of view.  For example: "This researcher has discovered"; instead of: "We discovered."  Or: "It was observed that"; instead of: "I observed that."  I know that this is something of a battle.  For 25 years I have told technical writing students to use the active voice, a conversational tone, and a natural first- or second-person point of view.  If an editor or your boss tells you to avoid using the first-person point of view and seems to be addicted to passive constructions . . . I guess that you had better do what she says.  Still, it helps to know what the issues are and to know that the old fashioned models are under attack by English teachers, technical writers, and most of all, by consumers.

Diction Level: 

We all know that technical writing aims at the standards of accuracy, objectivity, and formality.  You do not want to make jokes in a user's manual or a progress report.  But tech writing is no longer restricted to a kind of sleep-inducing  legal formality that many people believe lawyers use to keep non-lawyers from understanding legal documents.  Like so many issues, the choice of diction level should be driven by audience analysis.  Many people believe that a "technical document" is simply an "unreadable document."  How often do you read the instructions that come with some new product or device?  I remember a few years ago laboriously reading through a manual instructing me how to install a software program only to find that my kid had already installed the program and was running it!  He couldn't explain what he did or why he did it.  But it worked!  Robots do not read technical documents.  People read them.  The stilted works of a few years ago are no longer the standard, especially in the computer industry.  Manuals, reports, letters, and e-mail -- all achieve greater readability by being written in an informal prose style.  Informal does not mean grammatically sloppy.  Slang is not a synonym for informality.  There are at least four diction levels:

• Formal: the model is a legal contract, a formal speech, or an academic research article in a prestigious journal.

• Informal: use the first- or second-person pronoun.  Revise to replace stilted and wordy constructions, and jargon unfamiliar to any likely reader of the document.

• Colloquial: this is the level of conversation.  We cannot revise conversation and therefore are less concerned with grammatical standards.  We usually take care not to sound uneducated, but we do not want to be so cautious that we sound stilted or robotic.  The "dummy" series of books (e.g., Linux for Dummies) illustrates the colloquial level.  This level may be acceptable for writing e-mail to some of your close professional friends.  Even then, the standard is determined by asking yourself if you would be comfortable with the public disclosure of the document.

• Slang: this level often involves affecting a pose or playing a role for your friends.  It overlaps with body language and theatrical performance.  Minimal conceptual content for slang was perhaps recently set by the popular Budweiser commercials done by young guys in shorts and tee shirts who ask each other: "Wha . . . zzzz . . . up.   Ahhhhh . . . ."  Informal usage is a long way away from such slang performance.

Techno-babble & Robo-speak: 

Undoubtedly you find your writing to be a model of clarity -- at least when you are in the act of writing.  A couple of weeks later you may wonder what the document means.  Audience analysis is the mantra for technical writing.  Technical documents should be written to be perfectly intelligible to readers.  You do not want to be like the expert at the National Bureau of Standards who answered e-mail from a plumber who asked if hydrochloric acid would clean clogged drain pipes.  Like the expert, he was, the scientist wrote:

The efficacy of hydrochloric acid is indisputable, but its corrosive impact is  
incompatible with metallic longevity.  Consequently, its use is counter 
indicated for your proposed application. 

The plumber thanked the Bureau for advising him to use hydrochloric acid to clean drains, whereupon another expert tried to enlighten the plumber by writing:

The NBS cannot assume responsibility for the production of toxic, noxious, 
and corrosive agents caused by the improper and hazardous use of industrial 
grade hydrochloric acid on bathroom sewer pipes.  Alternative commercially 
available bathroom and kitchen products and standard household cleaning 
procedures are recommended by the NBS to maintain free-flowing 
household drains.

The plumber sent another e-mail to thank the conscientious folks at the Bureau.  He said that because of their technical advice he would recommend that all his clients regularly use hydrochloric acid to prevent clogged drains.  Finally, someone at the Bureau bluntly wrote:

STOP using hydrochloric acid!  It eats the hell out of metal pipes.

If you think the last message is too blunt or imperial, a good solution is to follow such commands (as you do with most recommendations) with an explanation or more detailed instructions for how to carry out the recommendations. 

Using Technical Terms: 

• Understand the meaning of jargon and technical terms.  Do not repeat terms that you do not understand.  I can't tell you how many times I caught my students repeating techno-babble I planted in case study data.  If it sounded technical, they would parrot it without understanding what it meant.  Do you want your boss asking you what a term means when you have simply repeated it without understanding it?  No matter how technically glib and popular, ask if terms are intelligible to the audience and whether really do save time, or whether they simply make you sound like an expert.  Showing off how smart you are does not do the job.

• Many documents are addressed to multiple readers.  Every reader should understand the jargon or acronyms you use.  Local, in-house acronyms do not go very far, even inside an agency.  Everyone at NM Tech heard about Tera every week.  (I assume you all know that "NM" is an abbreviation for New Mexico.)  Many English speakers know that terra, as in terra firma, is Latin for earth.  If they noticed the difference in spelling, I doubt that many people knew Tera was an acronym for "terminal effects research and analysis."  Now that I have explained that, do you understand what Tera is?  Not from this much denotative information, which is accurate but insufficient for audience needs.  Perhaps it is a medical research program into terminal diseases?  The reader needs to know that "terminal effects" in this context are understood to be artillery shells or missile payloads striking hardened targets, like tank armor.  If you object to breaking up the flow of your thought by parenthetically defining acronyms (and perhaps explaining this kind of context), consider making a glossary.

• For non-expert readers, seek to provide examples, illustrations, analogies or other kinds of familiar (non-technical) comparison.

• Edit for wordiness, pretension, and clarity.

Revising a Letter:

Delete all unnecessary words.  Do not eliminate sentences.

Dear Mr. Smith:

      Permit me to take this opportunity to thank you for your letter of 
inquiry, which I have just received, and for your request for a booklet 
describing our association and its services.
      In reply I wish to state that we shall be very happy to comply with 
the above request.  May I point out that a number of booklets are 
available; however, you may not find that all of them are useful for 
your immediate purpose.
      Please find enclosed herewith a list which will tell you what booklets 
are available at this time and which will enable you to order the ones you 
want.  Because of the fact that supplies of some of the booklets are limited, 
please permit us to suggest that you check the list and return it to this office 
in the enclosed, self-addressed, stamped envelope as soon as it is convenient 
for you to do so.
      In addition please permit me to state that in the future we shall always be 
glad to answer any of your questions about our services.  Please do not 
hesitate to write to us whenever you need information which we can supply to 
you by mail.

            Yours truly,

            Mr. Verbose

Original:

Revised: