oodt-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lewis John Mcgibbney <lewis.mcgibb...@gmail.com>
Subject Re: A Suggestion on Developing Documentation Based on the History of Experimentation
Date Thu, 09 Oct 2014 01:01:23 GMT
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*

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message