RE: [NeoStats-Devel] 3.0 documentation thoughts

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

I got no problem with this, but see below

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

Again, see my point below about this, but I think it's a good idea.


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

Have a look at the SecureServ and OPSB documentation. This is actually
docbook format, (SecureServ.xml) and as you say, we generate HTML via
docbook directly, and text only via lynx --dump README.SecureServ.html >
README.SecureServ

I didn't want to learn DOCBOOK XML, so I used xmlmind
(http://www.xmlmind.com/xmleditor/). There is a free WYSIWYG editor for
docbook files, and pretty good IMHO. 

Regarding splitting up the documentation for different modules (mentioned
above) that's fine, but I think we have to make sure its easy to get at. I
have no problem to RTFM to people that don't even bother to read, and based
on Josh's install guide, I think we also need a quickstart guide as well.
http://geocities.com/psyklopes/install.txt




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

I'd beg to argue on that. Some people (hang out in #neostats on irc-chat!)
don't even bother to look for documentation. Anyway, if its formatted as
HTML, we could easily split it up into sections and people can then go to
the section they are interested in ASAP.


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.


Actually here, I disagree. At the very least, the "runtime" documentation
should have information on the process to install 3rd party modules (how
many people have downloaded SecureServ into NeoStats-2.5.21/dl directory and
wonder why it doesn't compile?)