Mailing-List: contact dev-help@oodt.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@oodt.apache.org
Received-SPF: pass (athena.apache.org: domain of lewis.mcgibbney@gmail.com
 designates 209.85.217.180 as permitted sender)
MIME-Version: 1.0
In-Reply-To: 
 <CAOG8ptVZM64aCxvEJUGHexJtmSN0+5E1EWVOvV=vLOwHnBeeRA@mail.gmail.com>
References: 
 <CAOG8ptVZM64aCxvEJUGHexJtmSN0+5E1EWVOvV=vLOwHnBeeRA@mail.gmail.com>
Date: Wed, 8 Oct 2014 18:01:23 -0700
Message-ID: 
 <CAGaRif2a9uui=t_VGbCF=CEU3A2Sr5zf0Z3OS1kMjfJ5w+Ehgg@mail.gmail.com>
Subject: Re: A Suggestion on Developing Documentation Based on the History of
 Experimentation
From: Lewis John Mcgibbney <lewis.mcgibbney@gmail.com>
To: "dev@oodt.apache.org" <dev@oodt.apache.org>
Cc: "Mattmann, Chris A (388J)" <chris.a.mattmann@jpl.nasa.gov>
Content-Type: multipart/alternative; boundary=001a11c376b29c82be0504f2f8d6

--001a11c376b29c82be0504f2f8d6
Content-Type: text/plain; charset=UTF-8

Hi Bruce,
Documentation has been stripped.
Can you make this available somewhere else?
Thank you v much.
Lewis

On Wed, Oct 8, 2014 at 5:57 PM, Bruce Barkstrom <brbarkstrom@gmail.com>
wrote:

> During the last month, I managed to get a fairly difficult installation
> task
> to work on software I felt I had a critical need for.  I've attached the
> documentation I wrote as I went through the experience describing
> what I had to do.  I think we often denigrate writing documentation at
> the level of detail in the attached document as dealing with "newbies"
> who are a bit below our level of disciplinary attainment.
>
> Based on my experience, it's more appropriate to regard the documentation
> as showing the kind of professional level of instructions surgeons exhibit
> when they write down a procedure for other surgeons to learn how to do.
> We don't think surgeons should write down what they're doing in a one page
> summary intended for managers.  Managers don't have the training to know
> what kind of stitches to make that will hold a suture against a surging
> artery.
> If you ever have to have surgery (or have a person you care for undergo
> surgery) you want that surgeon to know the details of what he or she is
> doing, to understand the risks of the procedure, to have plans for dealing
> with the most common exceptions, and to close up the wound without
> losing things.  This isn't work for "newbies" -- it's a professional
> commitment
> we make to try to pass on what we've learned so people coming after us
> don't have to work so hard and make as many mistakes as we did.
>
> I think it would be helpful to take the exception handling procedures we've
> had to go through with Valerie and other folks on OODT and use the record
> (in e-mail and maybe elsewhere) to write up a professional summary of the
> procedures an inexperienced OODT user would have to follow to successfully
> install OODT and get it to work.  I didn't enjoy working through the
> rationale
> for why you couldn't just rely on the Debian Linux packages for the AdaCore
> GNAT GPL installation.  The same thing is true of the CAS PGE Crawler task.
>
> It is absolutely critical to help new (and even experienced) users navigate
> the treacherous path from starting out to successful and (relatively) error
> free operation.  The success of other folks in installing OODT is going to
> depend on getting the maintenance cost down to the LOCKSS level of
> a person-hour per month.
>
> Let's see what we can do to make this happen.  If we can, OODT will be
> a singular example.  If we do, it won't be luck, it'll be the really hard
> work
> we put in.  Our reward will be clear and it won't depend on how many grants
> we get or how many NASA medals we earn.  We'll know it - and that will
> suffice.
>
> Bruce B.
>


-- 
*Lewis*

--001a11c376b29c82be0504f2f8d6--