RE: [NeoStats-Devel] 3.0 documentation thoughts

Justin Hammond wrote:
> 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. 

It would be no harder than at present and should be easier. Instead of
doc/USERMAN being a long document, we have doc/neostats.html,
doc/statserv.html etc.

> 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

This is part of my reasoning for reducing the current information. Given 3.0
is simply extract, configure, make make install, a quick guide is unlikely
to be necessary since the README would already be a quick guide.

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

Yes and that will never change. I am aiming to catch those that try the docs
and give up on them for one reason or another. Having to scroll through
several pages of superfluous text is not a useful way to get people reading
the docs.

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

Yes, but why install extraction and build documentation into the runtime
documentation selection? There is no benefit whatsoever other than filling
the installation location with lots of information that is now useless to
the user since they have already performed all these steps. 

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

In part or the whole?

> At the very least, the "runtime" 
> documentation should have information on the process to 
> install 3rd party modules 

I never suggested this particular item should not be present in the runtime
documentation and would be covered in some way as a runtime task anyway. I
suggested that how to extract, call ./configure, make, make install should
not be "installed". The same should also apply to external module
documentation. 

However, the information on installing 3rd party modules is down to the 3rd
party. All we can really do is direct them to consult the documentation for
that module since we will never be able to suggest what may or may not be
part of a 3rd party installation process.

> (how many people have downloaded 
> SecureServ into NeoStats-2.5.21/dl directory and wonder why 
> it doesn't compile?)

This is largely due to a previous version of NeoStats where this was the
documented method of installation and some users when trying to help on the
forum still giving out this very instruction.

Mark.