Re: Passive voice -- a story

Subject: Re: Passive voice -- a story
From: Brett -dot- Peruzzi -at- FDC-INVEST -dot- COM
Date: Fri, 26 Jan 1996 13:53:55 -0500

Yes, we use a lot of passive voice in our programming documentation as
well. My group inherited the maintenance of it, and I don't think changing
hundreds of pages of it to active voice is a very productive use of our
time. Not that we don't use active voice when it's appropriate, but Emily's
example is a good one--code-level narrative--especially for mammoth
COBOL/JCL-based applications like many of ours--can be an appropriate use
of the passive voice, IMHO.

This active vs. passive thread has grown tedious--there are appropriate
uses of both, and as skilled techwhirlers we should know when (and when
not) to use them.

BTW, auditors, who are one of the reasons such programming documentation
exists, could care less whether it's in active or passive voice, as long as
it exists. Programmers don't get worked up over it either--perhaps because
it's what they're used to writing themselves! ;-)

Brett Peruzzi
Documentation Manager
First Data Investor Services
Boston, MA
Brett -dot- Peruzzi -at- fdc-invest -dot- com

From ??? -at- ??? Sun Jan 00 00:00:00 0000

I once wrote an entire manual in passive voice. (gasp!)

We called it "programmer documentation." Essentially, the manual was a
running narrative of thousands of lines of code -- what the code was
doing as it was doing it.

I began writing in passive voice, but found every sentence included
"the system" or "the program." [The system validates checks the input
number. If the number is not valid, the system displays an error
message. If the number is valid, the system retrieves the next unused
index number and assigns it to the record. Next, the system copies the
record to the XXX database... etc., etc.]

After reviewing the first two chapters, my boss (an excellent tech
writer) and I agreed that anyone would go batty trying to read the
thing -- even a couple of paragraphs of it -- with this repeated
element. Therefore, we decided after much thought to rewrite in
passive voice. [The input number is validated. If the number is not
valid, an error message appears. If the number is valid, the next
unused index number is retrieved and assigned to the record...]

In the end, we felt comfortable that we had made the best choice.
Anyone else ever done this? Or chosen another route for the same type
of task?

Emily Skarzenski
Deloitte & Touche/ICS - Chadds Ford, PA
eskarzenski -at- dttus -dot- com
71220 -dot- 341 -at- compuserve -dot- com

Previous by Author: for eric (listserve owner)
Next by Author: Re: Converting Windows Help Files to OS/2
Previous by Thread: Re: Passive voice -- a story
Next by Thread: Re: Passive voice -- a story

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads