Re: Passive voice -- a story

Subject: Re: Passive voice -- a story
From: Richard Mateosian <srm -at- C2 -dot- ORG>
Date: Fri, 26 Jan 1996 11:24:58 -0800

> 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.

> 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...]

Lines of code are commands to the system that executes them. Running
commentary should translate those commands into English.

CALL VALINP ;Validate the input
IF (CODE = ERROR) ;Was it OK?
CALL DISPERR ; No - display the error message
REPEAT ; Go back and ask again
RECNO = NEXT() ; Yes - Assign next unused index to the record

Here, as elsewhere, active voice makes for a clearer, more concise
communication. ...RM

Richard Mateosian http://www.c2.org/~srm/ President, Berkeley STC
Freelance Technical Writer srm -at- c2 -dot- org Review Editor, IEEE Micro


Previous by Author: Re: Dummies books
Next by Author: Japanese cartoon manuals
Previous by Thread: Re: Passive voice -- a story
Next by Thread: Noses miscellaneous


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


Sponsored Ads