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.
Date: Tue, 09 Aug 94 16:06:40 EDT
From: Nancy Paisner <nancy -at- hi -dot- com>
The battle of 'documents go first, software later' is one of
the hardest to fight, but well worth it. The basic paradigm to aim for
is 'Documentation is part of the product; so, like the software, it
has to be tested. It can't be tested until the software is done. So,
it can't be frozen before the software is frozen'
The reason this is a hard sell is that most software managers don't
really see the documentation as part and parcel of the product; they
see it as a description of the software, which is the *real* product.
In order to sell the view of docs-as-product, you have to really have
that view yourself. Fact is, documents *should* be tested before
they go out; nobody's perfect, and even the most conscientious
reviewers can miss things. But if you've tested all the procedural
parts of the book, and all your examples, you know that your document
pretty accurately describes the behavior of your software as the user
will see it. At least you know you aren't describing vaporware.
My experience has been that engineering management responds well to a
declared need by a writer to test the documentation; they understand
the concept as it relates to software, and know that it takes some finite
length of time. (Make sure they understand that it's not a substitute
for technical review, but an additional quality check.)
Just my $.02
Nancy
nancy -at- hi -dot- com
> Indeed!!
> The software we're documenting right now is exactly this way. We writers
> are being told, "Oh, sure, that's going to be working. No problem,
> put it in the manuals. The customer will *absolutely* need this
> information." Yeah, right!
> I can't wait until someone tells me three months down the road that
> I wrote instructions for or defined something that doesn't work
> right in the software. One more story to bring back to school to
> tell the new tech writing recruits! Luckily we include a
> disclaimer telling the user, in a professional sort of way,
> exactly what Mike said. Now all we have to do is make sure the
> users read it!
> > Thing is, documentation must go to press 3 to 4 weeks before the software h
>as
> > to go to the disk duplicator. You don't think developers are telling the te
>ch
> > writers "Oh, that'll be working by the time the code's frozen. No problem.
>In
> > fact, I know exactly how I'm going to do it....yeah, that's the ticket, I k
>now
> > *exactly* how I'm going to do it...."
> >
> > If management says "Document it...we *are* shipping the product with that
> > feature" - it's not the tech pubs dept's fault that the programmers couldn'
>t
> > get it to work.
