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