Re: Documenting A Moving Target

[Kathleen Walsh <kathleen -at- QANTEL -dot- COM>]

WandaJane Phillips wrote:

> Karen Gwynn/Datatel wrote:

> > Problem: I am trying to document a product that is still being developed

I think that is pretty standard.  Here's what I/we do:

1. We have have a program (PITS: Product Information Tracking System)
that tracks problems, requests, and new features reported by users, QA,
or added by development.  With this, I can see what the original problem
was, who reported it (in-house or field), what development did, and
who has the problem (development or QA).  It also tells me who the
developer and QA person are so I can go ask questions if necessary.

It also helps solidify my final documents (especially release
announcements that document the specific changes since each change
references a pit number--I can run a report and make sure that all the
things I said are new/fixed are closed by QA and that all the bugs we
list are open by QA).  we do occassionally have problems getting
development to add resolution remarks (tell us what they did), but at
the very least, they always change the development status and route the
pit to QA.  There's even a publish flag used to flag a specific pit for
inclusion/exclusion in the software announcement.  If a pit needs to be
included in a manual, it gets routed to DOC and then the document
is verifed closed by QA (and the pit closed).

2. If it's a major enhancement/feature release, development creates and
distributes an "external spec" to documentation, tech. support, and QA
so we all know what's going on.

3. when Development releases a new version to QA, they create a
release letter that contains a list of the changes they made (often just
a list of PITS numbers).

4. QA verifies the documentation when they are testing the product.

5. for major releases and some major products, we have weekly meetings
to keep everyone informed of what is going on and the projected
schedule.

6. one thing I do personally is, if development thinks something might
make it into the release (a new feature or bug fix), I document it and
give it to everyone for review:  it is MUCH easier to remove stuff (even
several pages) than to get everyone to read it (and agree on it) at the
last minute.  If what I have removed is major, I'll save it in a
separate file, because it'll usually make it in the next release.

Depending on the product and the scope of the changes, I can have very
little time to modify the document after the final development release.
 For our bulletin board updates, QA may get a release from development
at noon (or later) and it'll be on the BBS by 5pm (along with my readme
file documenting the changes).

Kathleen
kathleen -at- qantel -dot- com