TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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! ;-)
First Data Investor Services
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
Deloitte & Touche/ICS - Chadds Ford, PA
eskarzenski -at- dttus -dot- com
71220 -dot- 341 -at- compuserve -dot- com