[OpenAFS] Improving collaboration

Ken Hornstein kenh@cmf.nrl.navy.mil
Wed, 09 Jan 2002 18:06:56 -0500


>I wonder if it wouldn't be useful to use one of the open collaborative
>tools available on the network for maintaining some of OpenAFS's
>documents.  The CVS tree is appropriate for managing the source tree,
>but it seems unnecessarily heavy-weight for developing and maintaining
>information like the Project list[1], various HOWTOs (such as the
>oft-requested one on using Kerberos 5) and the FAQ.  I would suggest
>something like Wiki[2], which allows anyone to edit documents, would be
>a decent choice.  Another possibility is Faq-O-Matic[3].  Both of these
>could be run as CGI applications along with CVS at www.openafs.org.
>There are certainly other tools that could be used for this purpose; I'm
>not an expert on what's available.

I don't want to discourage the use of such tools ... but it's always
been my experience that it's not the tool that's the hard problem, it's
creating the content (the FAQ's I've seen created by FAQ-O-Matic never
seemed very good to me, but maybe I've looked at bad ones).

I think what we need more of are tutorials and answers to higher-level
questions (the answer to "Why can't I use LDAP to authenticate AFS?"
is rather complex); getting people to write those documents isn't easy
especially when you have a partially-volunteer effort like OpenAFS.
Writing the migration kit documentation was tough, because to make it
really useful, I had to write tons of documentation, and slugging
through that was difficult for me ... I wouldn't have done it if my
bosses weren't paying me for it.

I hope I'm not being to negative; I'm just saying that I'm not sure a
collaberation tool will solve documentation problems, not that there
shouldn't be one.

--Ken