Coda File System

Re: Improving Coda documentation

From: Stephen J. Turnbull <>
Date: Mon, 11 Apr 2005 17:28:20 +0900
>>>>> "satya" == M Satyanarayanan <> writes:

    satya> It would help to get a sense of priorities.  Given limited
    satya> resources, how should we prioritize our effort:

    satya>   (a) precise and accurate documentation (e.g. man pages),
    satya> that may not be friendly to a novice user

    satya>   (b) explanation of key new concepts in Coda relative to
    satya> POSIX (e.g. conflicts, RVM, reintegration, volumes,
    satya> ACLs,...) that may baffle an otherwise expert user

    satya>   (c) tutorial and step-by-step guidance to get new Coda
    satya> users up and running, even if many subtleties are glossed
    satya> over

I would say (1) Update the FAQ by having somebody troll the mailing
list; (2) install a FAQwizard like the one used by Mailman so that
either any user or "trusted" users can update the FAQ; then (b), (a),
(c) in that order.

Rationale: there's a _lot_ of useful information, already
well-written, in the mailing list.  Organizing this in an easily
accessible way is the biggest help to new users, and a FAQ is a pretty
standard way to do that.  The FAQwizard will help it stay up to date
with little effort from developers, who can just keep answering
question on list if they like.

I see (b) as next most important and (c) as least important for the
same reason: while we see a few people having problems with a basic
.deb or .rpm install, most of the ML questions from "newbies" are
actually from people who are quite clueful and have a good idea of
what they want to do with Coda ... and it typically runs aground on a
subtlety and/or a key concept that varies from "vanilla Unix
semantics".  (b) can probably be done in tandem with (1) by somebody
like me (that's 0.5 volunteering :-), with not so much input from you,
Jan, or even the SuperUsers like Greg and Ivan.

That allows you all to concentrate on (2) which probably should be
done in somewhere, so requires admin privs, and on (a)
which really should only be delegated to people you know quite well,
and even then can only be partly delegated.

School of Systems and Information Engineering
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.
Received on 2005-04-11 04:29:36