[WIDE] documentation

[Tom R. <Tom...@nc...>]

<sermon>

Documentation is good :-) Among other things, it shortens/shallows the
learning curve for subsequent users when one documents the solutions
one has found to the problems one has encountered. (This is what I've
tried to do with README and README-cvs.)

</sermon>

So: how to structure the documentation? Surely this particular wheel
has been invented many times--if anyone knows of links to good online
information, please let me know. (Surely someone (perhaps at FSF/GNU)
has written instructions on "How to Document an Open-Source Project,"
or something like that? Many conventions obviously exist.)

I can see 3 broad, top-level categories: documentation

0 in the code

1 in the distribution

2 on the web

For now, I'll just deal with 0 and 1; we also should discuss 2 later.
Some things that come to mind:

* 0: IMHO current code needs POD. I can work on this.

* 0: error messages. Verbosity should be an option for all commands.

* 1: .../cli/README: should tell someone who has just downloaded and
  unpacked an archive (and therefore can be considered "minimally
  competent," whatever that means :-) how to install the package, and
  where to go for more help.

* 1: .../cli/README-cvs: should tell someone with CVS access (and
  therefore a "reasonably competent user") how to install the package,
  and about any known CVS problems.

* 1: .../cli/doc is empty. What should go there?

* 1: info: IMHO installing cli should allow one to 'info sf'.
  Presumably this could also be built from the same source as the HTML
  for web-based documentation.  

YMMV, Tom...@nc...