Re: Documenting A Moving Target

Subject: Re: Documenting A Moving Target
From: Beverly Parks <bparks -at- HUACHUCA-EMH2 -dot- ARMY -dot- MIL>
Date: Wed, 21 Feb 1996 07:49:47 MST

Karen Gwynn asked some questions about where documentation fits
into the software development process and who is responsibile
for reporting the changes to the documentation.

> HELP! What do other people do? Do other software companies build in time at the
> end of the development cycle for doc to catch up? Whose responsibility is it to
> notify doc of all these changes as they occur (that's the other thing; I
> happened to find this item, no one told me of the change).

It is the programmers' responsibility to let you know how their
code changes will affect the documentation. In a perfect world,
before a line of code is changed, the programmer will have
prepared some documentation of his or her own, called something
like an engineering change proposal (ECP). An ECP documents why a
change is necessary, what modules of the code will be changed,
how the change will affect program functionality, what testing
procedures are necessary to verify the change, and *what
sections of the program documentation (i.e., users manual) will
be affected*.

In the real world, this seldom gets done before the programmer
starts coding. In the real world, this sometimes never gets
done. Sometimes programmers make changes and never tell anybody.
(Shhh.) Such undocumented changes usually come back to haunt the
programmer, though.

In some cases, it's the software testers who you hear from
first. They'll come back and say "hey, this documentation does
NOT match what's going on with this software." Then they write
their own ECP that says the documentation needs to be fixed.

Bottom line: When source code modifications affect the
functionality of the software, which in turn affects the content
of the documentation, it is the programmers' responsibility to
notify you.

=*= Beverly Parks -- bparks -at- huachuca-emh2 -dot- army -dot- mil =*=
=*= Certified _Ex-programmer_ =*=
=*= "I am not speaking for my employer." =*=

Previous by Author: Re: What is a SME
Next by Author: STC Conference - Seattle
Previous by Thread: Re: Documenting A Moving Target
Next by Thread: Re: Documenting A Moving Target

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

Sponsored Ads