Hello Satya,

On Sat, Apr 09, 2005 at 09:32:26AM -0400, M. Satyanarayanan wrote:
> is clearly time to do a major cleanup.   Jan and I will brainstorm
> on how best to do this.  We'd greatly appreciate your help, so we'll
> figure out how to carve up the work to make it easy for
> different people to contribute.

that looks great.

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

I would begin with a detailed "HowTo setup a test Coda system,
with two replicated servers and two or more clients",
with an explanation of every choice the new Coda admin has to do.

Do not let the novice admin take shortcuts  - they can not yet realize
the meaning of the shortcuts. One of misleading small things
would be e.g. examples on a private IP net without DNS.
Then the admin would not realize the fundamental thing about realm naming -
that it is not on the client, but in the (global) DNS.

A detailed step-by-step description shall inevitably include the
"setup your name resolution !!!" step which many of new admins
want to skip... a popular source of questions and confusion.

To be pedagogical, we should not use /etc/hosts or realms files,
they are good for workarounds when you know well what you are doing.
They are plain wrong when you don't. A new admin doesn't.
She does not know what it means to Coda.

Postulate working DNS. Emphasize the need of working DNS.
Provide a conveniency "simple-dns-serversetup" script?
Do not mention using hostnames or ip-numbers as realm names,
except with very small letters at the end of the whole exercise.

Don't take me wrong - it is very good that we have working shortcuts
which can help in certain cases. Just do not expose them, people would
believe that it is a "good way of thinking".

I would explicitely recommend using 4 machines for the experiments,
or if one does not have as many, combine them, but always remember
that these are _4_ logically isolated ones.
Emphasizing that fact would (hopefully) prevent several traditional
reasons for confusion.

I suggest using [my] coda-client-setup for testing Coda
as it is distribution-neutral and even works the same way on a couple
of other OS. I will be glad to improve it to make it more "pedagogical",
suggestions are very welcome.

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

That is a lot of work and possibly less of of the gain, as experienced users
can use productively even an out-of-date documentation, given available
updates, even when the corrections are separate from the docs.
Novice users, on the other side, need more "friendly" information anyway.

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

Imho it can be a very useful effort, but not the first one.
Important parts of it can/should be present in the "HowTo", which
should say not only "how" but also "why".

I'd make instead a very incomplete description which would mention
the key differences from the traditional filesystems, without going
into details, just to let a novice reader realize how it is thought.

I remember how hard it was to percept the difference between an NFS server
and a DFS cell...
Do not explain details, but paint the differences with BIG letters :)

The gory rvm/log/conflicts things come naturally in the "howto",
with the explanation of their relation to the general idea.

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

It is this step I would begin with.

Get a client up-and-running is trivial nowadays. The server setup will
never be trivial, there are many decisions involved.
The best we can do for the new admins - to show from the beginning
how to think to do it right.

My 2c
--
Ivan