Documentation

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 files.
The biggest advantage of texinfo is the simultaneous production of online info pages, and high quality LaTeX output for the production of printed manuals.

HTML

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

SGML

The SGML tools are capable of producing high quality output in a range of formats, including text, Postscript, RTF, HTML and TeX.