A bug in the code is worth two in the documentation.
Any publically released software should be documented. At the bare
minimum, this may be a comment block at the top of a script or an
accompanying README file.
A common convention is:
- A README file for the software project
- An INSTALL file, detailing installation instructions
- A man page for the program
- A copyright notice (this may be included in the README file)
There are a number of common formats used for text documentation. While
people will usually expect a man page, documentation may be delivered as
an info file or a set of HTML pages.
- Plain text
- The simplest format - guaranteed readable on any system with a monitor!
- man pages (troff)
- People expect man pages, and a man page also assists people searching for
your program with tools like apropos.
man pages are marked up with troff: you can use other man pages
as a template
- info pages (texinfo)
- The GNU project distributes software documentation in texinfo
format, which can generate hyperlinked and searchable info, LaTeX or HTML
The biggest advantage of texinfo is the simultaneous production of
online info pages, and high quality LaTeX output for the production of
- HTML pages are easily created and provide a hyperlinked document with
tables and images, but not all Unix systems will have a web browser
installed, and a user may not know where to find the web pages (whereas
info and man pages are readily found with the appropriate readers).
- The SGML tools are capable of producing high quality output in a range of
formats, including text, Postscript, RTF, HTML and TeX.