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.

Cheers,

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