Newsgroups: comp.text
Path: utzoo!censor!geac!nixtdc!jhm
From: jhm@nixtdc.uucp (John H. McMullen)
Subject: SCCS-type system for documentation?
Message-ID: <1990Nov5.022533.29625@nixtdc.uucp>
Summary: Is there an automated way to keep my documentation up to date?
Keywords: documentation current accurate automated
Organization: Siemens Nixdorf Information Systems
Distribution: na
Date: Mon, 5 Nov 90 02:25:33 GMT

I'm the (lone) technical writer in a development house; our product has
just been released and it looks like things will be going well from here.
We will probably need to expand in the future, and I'm dissatisfied with
our current documentation procedures, which will not be sufficient if
the product takes off and spawns other products and projects.

Our current documentation is intended for users of a toolkit, a suite of
programming tools and functions.  It is essential that the information be
accurate and up-to-date.  I need some way to a) automate as much of the
extraction from source as possible and b) freeze documentation at the 
version level (so I can go back and check how release 1.2 was documented,
for example, or so I can go ahead and document changes for the next
release as they are made by programmers).  We may also be adding another
writer, so the problem of two hands changing the source would then come
up.

It sounds like SCCS or RCS, doesn't it?  However, since the documentation
process (in our shop) doesn't *really* start to roll until the software
hits the testing stage (how else will I know what is actually in the release?),
there is the problem that I am lagging several months behind everyone else.

Someday, it would be nice to have something that runs through the source
and cross-correlates references to functions and programs in my *user*
documentation with the actual functions.  Even if it just notified me that
a function I have referred to has been modified in some way, I could keep
my documentation up to date.

Does anyone know of a software system to help this along, either on UN*X
or the Different Operating System?

John McMullen
jhm@nixtdc.UUCP