[OpenAFS] How to volunteer?

Russ Allbery rra@stanford.edu
Mon, 09 Apr 2007 10:25:55 -0700

Derrick J Brashear <shadow@dementia.org> writes:

> Russ Allbery has been coordinating documentation work. Please talk to
> him before you start on something if you'd like to avoid duplicating
> effort.

Hi Jason,

I'm sorry about the delay.  I was on vacation.

Here's where we're currently at:

The Administrative Reference has been converted into separate POD man
pages for each command, since that's basically what it already was (just
in HTML).  Considerable work remains to update that POD documentation to
reflect the current behavior of OpenAFS (for example, there's no
documentation of dynroot, no mention of Kerberos v5, many fileserver
options are undocumented, the afsd switch documentation is out of date,
and so forth).  I've collected as many of those deficiencies as I know of
in doc/man-pages/README.  Any contributions to correct any of those
deficiences are very welcome.  This is one easy place to start.

The other reference manuals (the Administrator's Guide, the Quick Start
Guide, and the User's Guide) are more manual-like in their structure.
After some on-list discussion, we picked DocBook as the format to use
going forward and the existing HTML files have been converted to DocBook
with a script.  This means that the markup could use a lot of cleaning up
and the content is even less updated than the man pages.

I did some *very* initial work on the Quick Start Guide, just to get the
makefile working and to try some simple modifications.  Simon Wilkinson is
currently working on making more extensive modifications.  If you want to
work on the Quick Start Guide, please coordinate with him to avoid
duplicate work.

The Administrator's Guide and User's Guide have not yet been touched.  Of
those, the latter is probably in the best shape, in that the user commands
and behavior haven't changed as much.  If you'd like to start working on
one of those, that would also be great.

Basically, please feel free to pick any of the documentation and just let
me know what you're working on.  As you finish modifications, the easiest
way for me to process those changes is as unified diffs, but if you want
to send a complete replacement file, I can deal with that as well.  Please
submit any modifications as bugs to openafs-bugs at openafs.org, and
please either copy me on the message or let me know the RT number after
the bug has been submitted since I don't always track all the bugs.

Let me know if there's any other information I can provide or anything I
can help with.  Thank you very much for volunteering!

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