Dear All,

As a coda newbie who started experimenting last week I would say Ivan's take 
is spot on. A HowTo needs to cover what to do, why, and what not to do. 
Important conceptual differences need to be explained at this stage as some 
steps will be confusing if the underlying differences aren't explained.

I have been keeping a record of what I've been doing, with the intention of 
producing a HowTo of some sort so others can avoid some of the traps I've 
fallen into. Patrick seems to have similar intentions (thanks for the rtf doc 
btw) and has been asking many of the questions I would have been asking. I 
will gladly contribute in whatever way seems useful.

While searching the list archive I found an anouncement of a wiki at 
http://coda.wikidev.net which seems to have gone unused. Perhaps this would 
be a good place to start on some colaborative documentation.

Thanks for all the good work

Al

On Monday 11 April 2005 11:53, Ivan Popov wrote:
> 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