Newsgroups: comp.text
Path: utzoo!telly!eci386!woods
From: woods@eci386.uucp (Greg A. Woods)
Subject: Re: SCCS-type system for documentation?
Message-ID: <1990Nov8.232153.14555@eci386.uucp>
Summary: why not SCCS?
Keywords: documentation current accurate automated
Reply-To: woods@eci386.UUCP (Greg A. Woods)
Organization: Elegant Communications, Inc.
References: <1990Nov5.022533.29625@nixtdc.uucp>
Date: Thu, 8 Nov 90 23:21:53 GMT

In article <1990Nov5.022533.29625@nixtdc.uucp> jhm@nixtdc.uucp (John H. McMullen) writes:
>[....]  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.

Either you're wrong and the answer is indeed SCCS or RCS, or I don't
understand your problem.

Part (b) and [the unassigned] part (c) are solved by either SCCS or RCS.

This is a total project management problem affecting management,
programmers, and technical writers; not a documentation only problem.

If you were documenting stuff prior to code modifications, SCCS or RCS
would not be able to predict what source code changes were to be made
for the new release, but if the changes are already made, and you are
documenting after the fact, then SCCS or RCS solve the problem nicely
by allowing you to review the actual changes to code during testing and
documentation.

One thing that might help would be to enforce, and use MR's (SCCS
Modification Requests) to control and track sets of changes to sources
that affect some particular behavior (i.e. bug fix) of the product.
The MR's can then be used to control changes to the documentation for
this new behavior.

Note that MR's could also allow you to document changes to be made,
then the programmers would make the changes against the MR's, making
the documentation "real".  You could then check deltas to sources
against all MR's to find outstanding MR's.

SCCS or RCS, when used on the doc's themselves will help control
releases of the documentation, allowing you to go back to old
versions, and controlling multiple access to the document files
(assuming you use some sane ASCII method of editing and storing your
documentation).

Part (a) can be solved by a simple set of sed scripts, if you can keep
your programmers under control.... :-)  [You'll have to do that to use
SCCS or RCS anyway!]

If you do indeed want to use SCCS, look up a tool called sccs, written
by Eric Allman, and included as part of the AT&T free code in BSD4.x
(i.e. available everywhere, such as uunet, and the FSF).

> 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.

Sounds a lot like a CASE tool, or maybe you should switch to Smalltalk-80!
-- 
						Greg A. Woods

woods@{eci386,gate,robohack,ontmoh,tmsoft}.UUCP		ECI and UniForum Canada
+1-416-443-1734 [h]  +1-416-595-5425 [w]    VE3TCP	Toronto, Ontario CANADA
