Coda File System

Plan to revise documentation

From: M. Satyanarayanan <satya_at_cs.cmu.edu>
Date: Tue, 26 Apr 2005 19:04:44 -0400
Thank you for the feedback and many suggestions regarding
documentation.   Based on this input, here is how we have
decided to proceed:
 
1.  Highest priority is accurate man pages.   We will
    stop using docbook. It made the build depend on a whole
    suite of parsers and stylesheets that weren't
    necessarily installed when people tried to build Coda
    from sources.  And all the docbook2man parsers still
    required additional tweaking ('-' -> '\-', etc.) Instead
    we will simply use native nroff, which can be used
    without problems on any system that does Unix manpages,
    and there are several programs to convert them to
    readable HTML if we ever want that.  Editing is also
    somewhat easier since there is a pretty usable open
    source tool for editing man pages
    (http://wolfpack.twu.net/ManEdit/).

    A soon-to-be-released Coda-6.0.9 will have all the man
    pages in nroff format, but they may not be accurate yet.
    Our goal is to make them accurate by a soon-to-follow
    Coda-6.0.10 release.
 
2.  Next priority is "official" manual.
    We will separate the current manual into an internals 
    manual and a system administrator's manual.  The system
    administrator's manual is higher priority; internals 
    manual (including things like RPC2, LWP, etc.) will follow.
 
    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).  The community can contribute by adding
    comments if they notice unclear descriptions and missing
    or outdated information in the manual.  From time to time,
    we'll merge the comments into the next release of the
    "official" manual.
 
3.  The wiki will be a place where the community can freely
    add useful pieces of information about Coda.  We can't
    promise that the information on the wiki is correct, as
    we are not going to be able to track or correct those
    changes.  The kinds of information that are already in
    the Wiki (e.g. performance measurements, useful tips on
    installation, optimization, etc.) are perfect for Wiki
    format.   But we'll keep the official manual out of the
    wiki, as discussed in (2) above.
 
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.  
 
Please speak up soon if you see any serious problem with the above plan.
Otherwise, we hope to get started on these changes soon.  Help from
volunteers in the cleanup will be gratefully accepted!

          -- Satya
Received on 2005-04-26 21:58:21