[OpenAFS] Improving collaboration

[Ted Anderson]

On 9 Jan 2002 21:47:06 +0100 cg@cdegroot.com (Cees de Groot) wrote:
> A Wiki is always useful (my credo as a project manager: "here's a Wiki
> and a mailing list - use it for 6 months, if you still want more after
> that, yell").

I've long found Wiki attractive, though it was a bit confusing at first.
I worry a bit that the format might be a bit off-putting for potential
contributers.  Since I share Ken's worries (see below) about getting the
necessary support from the community, this may be an issue.  Are there
other collaborative authoring tools that are both free-form as well as
highly intuitive and accessible?

> However, wouldn't it be an idea to use AFS for this? I'd say that most
> people here have AFS installed, so you could just put a designated
> part of the website in AFS, with public (wiki-like) parts, and maybe
> some parts that have ACL's for certain project teams, and 'canonical
> official' parts that are just writable by OpenAFS folk. Eat your own
> dogfood...

I'm fine with using AFS to collect and support collaboration.  But the
web interface solves numerous problems that just shared access to flat
files doesn't.  At the very least, we want to strongly encourage the use
of hyperlinks, so a browser-centric approach is a must.  Then, whether
AFS is in the background is more a question of what is convenient for
the webmaster.

On Wed, 09 Jan 2002 18:06:56 -0500 Ken Hornstein <kenh@cmf.nrl.navy.mil> wrote:
> 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 don't want to minimize the difficulty of writing good documentation.
However, I believe that the right kind of encouragement can do wonders
for extracting the requisite effort from participants.  There two key
ingredients to this encouragement: a low threshold of participation and
a sense of accomplishment afterwards.

Here's a recent example from my experience.  I recently wrote a Perl
module to compute MD4 hashes without using C-code.  Having expended the
effort to modulize the code using the same OO interface used by other
modules in the Digest:: family, I thought I should contribute it to the
CPAN archive.  In the end doing it "right", with a makefile and
integrated test code was just too hard.  I almost didn't bother, but
then decided to do it "wrong" instead.  In this case CPAN is setup to
make contributing hard (at least for occasional contributers) and make
consumption very easy.  Contributing code and documentation to OpenAFS
has a similar work function.  This makes sense for CPAN, but in the case
of informal AFS information, the consumers are motivated, they are
trying to resolve some problem and get their system working, while the
potential contributors are unmotivated, their system has now started
working.  This argues for reversing the usual work functions.

Mailing lists have a very low barrier for contributions (some might say
too low) and that is crucial to their value.  One problem, however, is
that extracting information from a mailing list archive after the fact
can be very challenging.  So, my suggestion is to augment the mailing
list mechanism with something very little harder to contribute to, but
which makes finding answers much easier.

As such, the standard of quality does not have to be very high.  As long
as the resulting information is more accessible than a mailing list
archive it can provide value.  As a first approximation, just collecting
messages relevant to each subject would be a start.  This provides the
value of collecting messages with diverse subjects and from different
threads scattered over a long period of time into a single place.  If,
now and then, a knowledgeable person can get the gumption to purge
obsolete information, then it further increases the value to
help-seekers.  These documents also provide a point of contact where
some who got help can report experiences with the advice, pro or con.
This provides a key bit of the second kind of encouragement: a sense of
accomplishment.  It is easy to imagine feeling that you've left things
better than you found them and paid-off a bit of the karmic debt
incurred by receiving the advice in the first place.

> 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 agree.  Perhaps the rough collection of information in these proposed
documents would be helpful raw material for the potential author of more
detailed, comprehensive and polished documentation.

> 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.

I'm trying to argue (at excessive length, I now see) that a rough tool
would be better than no tool at all.

Ted Anderson