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.
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." =*=
