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