RE. Checking for technical accuracy?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Sona Mehta wonders: <<what do  most of you do to ensure that the documents
you  produce are technically accurate.>>

Release them on unsuspecting users and wait for the inevitable lawsuits.
Then hastily fix them. <g>

<<Technical review by the developers is  one way I know of but in the real
world, the developer you want is no  longer with your company or has now
assumed some other role. What helps  you to write a technically accurate
document ( Eg Programmer's Manual)  in the first place?>>

Facetiousness aside, we do our best to run everything we produce through a
third-party review (though our software development process is sufficiently
new and immature that this isn't done nearly as well as I'd like). As
writer, I'm too close to what I've written to be a reliable judge of its
accuracy and completeness, and even though I'm also the editor here, I can't
edit myself nearly well enough for self-review to be safe. Plus, I'm not the
SME. Speaking of whom, our SMEs (or would the plural be smee? smen? smice?)
have the same problem, only worse; they already know what the software does,
and neither threats nor operant conditioning have proven effective at
getting them to do reliable reviews. Giving them a superbly edited document
<g> helps, since then they don't spend quite so much time quibbling over
typos and can focus on content, but they still miss things.

So we're back to those third-parties: we usually get our summer students and
research technicians (who are <Fe> expendable and easily replacable </Fe>,
not to mention entirely unfamiliar with the docs or the product) to run
through our documentation, step by step, to make sure everything works as
promised. <Fe> If there's a problem, and they survive the experience long
enough to inform me</Fe>, then I make the appropriate corrections. I'm not
aware of any other reliable way to produce a good technical check. You'd
think that responsible, professional SMEs could do this work, but experience
has shown that (i) it's not really one of their skills and (ii) rumors
notwithstanding, they're human too, and make mistakes. Often big ones.

<<Is  a sign off the most common way of saying that the document has now
been completed?>>

Yes, and it's a smart thing to implement to cover _your_ ass, but don't ever
let yourself trust that a signature means the reviewer actually did the
review. Most times it does, but I've had enough unpleasant surprises to be
very skeptical of signoffs as a quality-control measure. ("Everything looks
fine, Geoff. Let's print it." <stunned silence> "You mean I should leave all
those questions and marginal notes in the text so the client can see them?
Gee... I thought we'd want to remove them, but you're the SME, so they must
be technically correct.")

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer