Re: Passive voice -- a story

[Brett -dot- Peruzzi -at- FDC-INVEST -dot- COM]

     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