STAR   Computing Tutorials main page
How to document software packages
Offline computing tutorial

Package documentation resides in the CVS repository together with the code. There are two levels of documentation for each package:

  1. A README file in each package directory with a brief description of what the package is for, what subsystem domain it resides in, who the authors are, and a brief reverse chronological history of revisions to the package. That is, the README file should give a concise picture of the purpose of the package and its history and status.

  2. The doc subdirectory under the package directory which contains reliable information about performance and usage of the package. The main page should be in index.html. The main page may contain little more than links pointing to the doc resident elsewhere; it's up to you. The important thing is that the page guide the user through detailed documentation enabling them to understand and use the package. 
                       PackageDirectory
                   |-----README
                   |-----doc
                          |---index.html
The documentation is most easily accessed via the software guide linked from the computing homepage. README files and doc directories for each package are linked there.

Documenting CVS commits

When you commit a change to the CVS repository you must supply a comment as to what the change is all about. It is important that you make the comment descriptive enough to be useful. If one line is all you need you can just use -m "comment" on the commit command line, but you can also enter more extended comments by leaving off the -m option. You will be put into an editor in which you can enter as descriptive a comment as you like; when you save+exit the editor your comment will be saved and the commit processed. The editor used follows the CVSEDITOR environment variable if it is set, otherwise the EDITOR environment variable (eg. setenv CVSEDITOR "emacs -nw").

If you have changed multiple files for multiple reasons you can also ensure that the proper comments are associated with the proper files by committing the files separately, eg.

        cvs commit -m "Comment 1" file1
        cvs commit -m "Comment 2" file2 file3