Documentation HOWTO

top | work | programming | documentation | personal | contact

intro

Scientists are notoriously sloppy when it comes to documenting the software they write. Yours truely is no exception, but there is an easy way of generating some documentation with a good bang for buck ratio. The only prerequisite is that you have Perl installed (and there's no reason not to).

pod

If you've ever looked at the source of a man page, you may have given up on the idea of writing them for your apps. Fortunately, people like Larry Wall exist, and as a result, a document format called pod (for plain old documentation). This is some sort of markup language which is simple to learn, and can easily be converted into other formats. So, I suggest you learn to use pod, by reading the pod man page.

The pod source can easily be converted to other formats:

For pod2man and pod2html, the output can be controlled by a number of command line options. The --help switch gives you more information.

tip: for previewing, it is handy to define

    alias pman 'pod2man !* | nroff -man | less'

(for tcsh, or something to that extent for other shells). It will give you a good idea of how the man page will come out of a pod file, or a Perl script with embedded pod.

content

Apart from the file format, documentation is most useful when it conforms to the conventions. This essentially means sectioning your documentation into predefined categories. Borrowing from the pod2man manual page:

section	content
NAME	a comma-separated list of programs or functions documented by this podpage
SYNOPSIS	a short usage summary for programs and functions
DESCRIPTION	long drawn out discussion of the program
OPTIONS	program options, sometimes combined with the description
RETURN VALUE	what the program or function returns if successful
ERRORS	exceptions, return codes, exit stati, and errno settings
EXAMPLES	some example uses of the program
ENVIRONMENT	environment variables this program might care about
FILES	files used by the program
SEE ALSO	other man pages to check out
NOTES	miscellaneous commentary
CAVEATS (WARNINGS)	things to take special care with
DIAGNOSTICS	possible messages the program can print out -- and what they mean
BUGS	things that are broken or just don't work quite right
RESTRICTIONS	bugs you don't plan to fix :-)
AUTHOR(S)	who wrote it
HISTORY	programs derived from other sources sometimes have this, or you might keep a modification log here



Inclusion of any of these sections depends on what is documented, but any good documentation at least features the name and a synopsis.

top | work | programming | documentation | personal | contact