jhm@nixtdc.uucp (John H. McMullen) (11/05/90)
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
woods@eci386.uucp (Greg A. Woods) (11/09/90)
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
roger@gtisqr.uucp (Roger Droz) (11/16/90)
In article <1990Nov5.022533.29625@nixtdc.uucp> jhm@nixtdc.uucp (John H. McMullen) writes: >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. We have been experimenting with Brian Berliner's CVS at our site. I have been making a few hacks to it to make it more suitable for documentation. CVS is a front end to RCS, available from the archives of comp.sources.unix. The advantages over RCS are that CVS deals with directories of files, and permits several writable copies to be checked out at once. While originally developed for source code, I think it will work well for any sort of ASCII files. Thanks to this newsgroup, I now have a *roff macro that sets the DT string used by the mm macro package to the date the file was checked into RCS. The CVS symbolic tagging capabilty allows me to retreive the man pages that applied to a given release using the same key as I would use to get at the corresponding version of the source code. CVS is quite used to the notion that not all files change in every release. As you may gather from the above, we haven't yet used CVS for any really serious (large) documentation effort. I am posting rather than mailing because I am interested in other's experience using a source code control system for documentation. >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. You are dealing with fairly low level tools. Would ctags(1) help you? Given the name of a function, the ctags facility can show you the function definition. Somewhere in the vacinity should be a block of comments giving a function description of the routine. The file output by ctags contains the names of all functions and the file in which they were defined. Given a list of files that have changed, ctags could help provide a list of functions that might have changed. ____________ Roger Droz UUCP: uw-beaver!gtisqr!roger () () Maverick MICRoSystems / Global Technology International (_______) Mukilteo, WA ( ) | | Disclaimer: "We're all mavericks here: | | Each of us has our own opinions, (___) and the company has yet different ones!"