Re: Passive voice + Writing Func. Specs

Subject: Re: Passive voice + Writing Func. Specs
From: Gwen Gall <ggall -at- CA -dot- ORACLE -dot- COM>
Date: Tue, 29 Nov 1994 13:31:01 EST

In-Reply-To: CNSEQ1:TECHWR-L -at- VM1 -dot- ucc -dot- okstate -dot- edu's message of 11-29-94 09:12

Ellen Adams asks:

When is it okay to use the passive voice in documentation?


In software documentation, at the design document and functional specification
stage. You can use "active verbs", etc. but you must say "Users will generate
the pcode using the mcode facility..."

I don't fully write these--I do major edits for developers, although it seems I
might take a more active role in future. The model we are considering is this:

Regular design meetings, where I am an "active observer". I write down salient
points, and the meetings are videotaped. When decisions are made, I document
what these decisions are, and plug them into a design document/functional
specification template. This document gets reviewed for accuracy, and I use it
to build the user manual, and other materials. Because I am involved in the
design process, I can provide input regarding usability, user interface design,
etc., plus I will get a feel of the product development before I must write
about it for users.

(Right now, I am scrambling to write down anything the developer says, in a
single meeting, _after_ he's coded it. There's no design doc., no syntax list,
nothing. But, in the developer's defence, we have had incredible pressure, and
an unrealistic timeline.)

Has anyone else as a technical writer "owned" the design and functional specs.
out there? Any advice or recommendations? Has it been a waste of time going
through the whole design process, and have you had the technical expertise (I'm
no programmer, though I understand the concepts) to write adequately?

Any thoughts would be appreciated.


Gwen (ggall -at- ca -dot- oracle -dot- com)

Previous by Author: Re: World Wide Web
Next by Author: Re: Long post on passive voice
Previous by Thread: Re: Book Master Replies
Next by Thread: Long post on passive voice

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

Sponsored Ads