Re: Metrics

Subject: Re: Metrics
From: Undetermined origin c/o Postmaster <POSTMASTER -at- OSUVM1 -dot- BITNET>
Date: Tue, 9 Aug 1994 15:13:45 -0600

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.

> Shelly
> larock -at- tycho -dot- arh -dot- cdc -dot- com


Previous by Author: Re: TECHWR-L Digest - 5 Aug 1994 to 6 Aug 1994
Next by Author: [no subject]
Previous by Thread: Re: Metrics
Next by Thread: Re: metrics


What this post helpful? Share it with friends and colleagues:


Sponsored Ads