This page is to record a suggestion made by David Candlin in a mail as a practical way to maintain software documentation today with the code. It is expected that the future lies with XML however we clearly require solutions for today.
The current recommendation is to write LaTeX, and to publish it as HTML, Postscript and/or PDF.
The latex directive \htmladdnormallinkfoot (available with \usepackage{html}) has the nice feature of generating a hyperlink in LaTeX2HTML, or a footnote displaying the URL in the LaTeX processor.
If you write your makefile correctly, it will run latex2html and latex followed by dvips, and then install the output files in the installed/share/doc directory of the release. There's an example in Applications/Paso/GNUmakefile.in. The great advantage of this is that to update your documentation, you edit the latex and tag it....the rest is automatic. You may prefer to control LaTeX2HTML a little more for example if you specify -split 0 produces a single html document and -split 2 will generate a new HTML page for each \chapter.
To link the information into the web the easiest solution is to request a symbolic link to the directory. For example /afs/cern.ch/atlas/www/GROUPS/SOFTWARE/OO/applications has a symbolic link: Paso -> /afs/cern.ch/atlas/www/GROUPS/SOFTWARE/OO/dist/current/installed/share/doc/Paso/ so that the URL http://www.cern.ch/Atlas/GROUPS/SOFTWARE/OO/applications/Paso/ works as expected.