[OpenAFS-Doc] State of the documentation presentation?

[Russ Allbery]

Jason Edgecombe <jason@rampaginggeek.com> writes:

> Steven Jenkins had the following to say:
> ==============================================================
>
> doc/README, doc/man-pages/README summarization would be a start.  It
> would be helpful to know who is tackling what, and how best to
> coordinate with them (e.g., the comments about Simon Wilkinson working
> on the Quick Start guide).  My assumption is that between now and the
> Workshop, you will probably finish out this list of 'no man pages exist'
> from doc/man-pages/README:
>
>       copyauth
>       fs cscpolicy
>       fs memdump
>       fs minidump
>       fs monitor
>       fs rxstatpeer
>       fs rxstatproc
>       fs setcbaddr
>       restorevol
>       rmtsysd
>       vldb_convert
>       vos clone
>       vos setfields
>       vos shadow
>       vsys
>
> so to me, the interesting questions are
>
> - what's next?
> - what kind of skillset is needed to help with the docs on which part?
> - who is actively doing work on the docs, and how should people
> coordinate with you (or whomever is actively doing things)

For the man pages, there are a lot of other issues listed in the README
that do need to be resolved still.  I think the fileserver documentation
still needs a lot of work, there's further cleanup required to remove
kaserver references and assumptions, dynroot needs more documentation, and
I think a general check for where we need to mention Kerberos v5 would be
useful.

However, there are two things that really stand out:

* We need to be generating HTML versions of the man pages automatically
  and installing them on openafs.org somewhere, and we likewise need to be
  generating HTML versions of the current DocBook pages in CVS and
  displaying those on openafs.org instead of the old IBM manuals.

* We need to figure out how we're going to maintain the DocBook manuals.

My personal feeling on the latter is that one of the biggest barriers to
entry on DocBook (and one of the reasons why the POD pages have gotten
much more attention) is that DocBook is ginormous and horribly
intimidating.  I have no idea what tags to use for common things when
writing in DocBook, and the manuals and references leave me drowning in
too much information.

I would really like to see someone write up a simple DocBook style guide
that duplicates just enough of the DocBook manual to say "here's the basic
structure, here are the tags we actually use, use the following inline
markup tags for the following things, and don't use anything else not
mentioned in this guide."  Even a starting point would be great.

Then, once we have that, we need to take a comprehensive pass through the
existing manuals and bring them in line with that style guide.  The result
will be something that we can actually update and maintain without being
lost in the necessary tag conventions.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>