Coda File System

Re: Plan to revise documentation

From: Greg Troxel <gdt_at_ir.bbn.com>
Date: 27 Apr 2005 09:31:38 -0400
That sounds good.  It has been a big problem not to have man pages,
IMHO.

  Editing is also somewhat easier since there is a pretty usable open
  source tool for editing man pages (http://wolfpack.twu.net/ManEdit/).

I hope that results in a new file for which 'diff -u' shows only
semantic changes and doesn't munge everything else.  I use emacs for
man pages.  Please specify in the Makefile/README or someplace which
macro package, and that probably deserves somelooking into.  I
suspect it's -man, rather than -mandoc.  As for compat, I'd say if it
works on BSD, Linux OS-X, and Solaris you are all set.

  The "official" versions of both manuals will be released
  as HTML (both on-line browsable and as a tarball) along
  with a PDF or PS version on our website, where the
  on-line version has the ability to add user comments at
  the bottom of each page (that Jan explored with some of
  you on codalist).

Presumably you will use docbook for these, and that sounds fine.  I'd
like to see the source released or perhaps just accessible via CVS.
>From the packaging point of view, I'd like to see
coda-manual-x.yy.tar.gz available, and to be able to write package
control files (e.g. NetBSD pkgsrc) to install to
${LOCALBASE}/share/doc/coda.  So having a released tarball with html,
ps, pdf would be nice.  I'd just as soon it have the docbook too, but
I wouldn't install that.

  [wiki]

Sounds good, but non-ephemeral questions/answers on the wiki are
probably fodder for the real docs (resource constraints understood).

  4.  Lowest priority are tutorials, howto's etc.  These are
      probably best done as contributions by the community.
      The most likely path here is that such documents would
      be constructed on the Wiki and at some point once they
      have been refined and checked for accuracy we could put
      a 'blessed' version on the Coda website in both HTML and
      PDF format.  

I think that Coda would be better off in the long run with a bit more
open development model.  I'm not asking you to give cvs commit privs
to lots of people, or indeed anyone outside of CMU, but even if [cmu]
just put the barest outline of tutorials in docbook cvs and invited
patches.  I would avoid conflating 'blessed' and 'in cvs/released on
coda website' - it seems easy enough to have a document status comment
at the beginning.

All that said, if the administration manual does its job, tutorial
would just be a walkthrough of a few different setups, backup/restore,
repair scenarios, for the purpose of getting people oriented enough so
that when they read the admin manual it will make sense.

    Greg (coda user since 1997 or 1998 - don't remember any more)

-- 
        Greg Troxel <gdt_at_ir.bbn.com>
Received on 2005-04-27 09:33:36