[OpenAFS-Doc] Forwarded documentation rant

[Chas Williams (CONTRACTOR)]

In message <4BCB8E43.8030102@secure-endpoints.com>,Jeffrey Altman writes:
>into a source form (including consistent formatting and
>indexing) that could be used by contributors to submit
>changes.  All of the documentation that we have is now
>in DocBook format and the man pages are in Perl POD format.
...
>It has only been in the 18 months that the XML sources
>have been available in this easy to edit form.  It has
>been my hope that with the improved source format availability
>that a broader range of users and administrators would
>contribute to the depth, breadth, and usability of the
>available documentation.

the formatting isnt entirely consistent.  it is close however.  it was
inconsistent in the original html, i tried to correct it somewhat in
the xml but alas i am only a human.  someone really needs to write (and
i was going to do it) a document that decribes what tags should be used
in the various examples.

other projects have similar style guides and i really think it would help
people out.  learning docbook is pretty easy but applying it consistently
is not easy.

on a general note, people might be intimidated by the sheer volume of
documentation.  usually, it is not enough documentation when it comes
to open source projects.  openafs is one of the few to my knowledge that
actually has a pretty complete set of documentation.  some of the docs
are outdated now, but at one point is was correct and consistent.