[NeoStats-Devel] 3.0 documentation thoughts

As promised, my thoughts on 3.0 documentation.

Firstly, I think we should make a slight change to current documentation for
the core. Rather than documenting the modules within the main NeoStats
USERMAN file, I suggest we separate the documentation for each module into a
file in the appropriate module directory. This should assist maintainance of
documentation for modules and allow us to easily add/remove modules and
their documentation without affecting the main core manuals. 

Previously we have documented the configuration file both within the file
and in associated documentation. This has lead to one or the other being out
of date to changes in the configuration system so I suggest all
configuration documentation is left purely as comments within the
configuration file (makeconf as far as we are concerned) and any references
from other documentation reference the configuration file comments as the
primary source for information. 

Personally, I think all documentation should be provided as HTML rather than
TXT. This has the advantage of allowing us to provide online copies of all
documentation for the current version easily. We could have a system of
index.html as the local index in NeoStats/doc which provides access to
neostats.html, and multiple modulename.html files. We could provide default
files for those modules not included in the core that instruct the user to
download and install the module. HTML can usually be parsed through a text
based browser on a shell so other than on a really anal installation that
does not provide a HTML reader, users should have no issues reading the
files. If this is a likely scenario, we can provide a text copy of the
files, but I think HTML as our primary format is the way forward.

Experience has shown that some people do not seem to read our documentation
no matter how good it is. However, I think in some cases this is down to
some superfluous information that is included. As an example, showing the
output of configure/compilation just adds a page or more of text that is of
no real use to readers and makes the documentation less likely to be read if
a person has to page through all this before finding information they wish
to read. I think we should try a "less is more" approach so that we provide
a concise set of documentation that is both easier to maintain and more
useful to end users. 

Rather than a mere dump of a successful configure/make/make install, I think
we are better to remove this and instead consider it will usually work but
discuss possible examples of a failed configure/make/make install. E.g.
after the instructions to type make note that if a user sees "error
compiling myfile.c" try XYZ/FAQ/Forum etc. We may be able to create a
generic file/resouce that will cover the majority of problems encountered.

On a similar note, I think configure, compilation and installation
instructions for the core and external modules should be a local document
that is not actually installed. This makes the final installation
documentation more targetted to runtime use rather than including
information on tasks already accomplished. This should also help with
keeping documentation up to date since we have less information to edit
given the build process is unlikely to change.

Mark.