oodt-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Mallder, Valerie" <Valerie.Mall...@jhuapl.edu>
Subject RE: A Suggestion on Developing Documentation Based on the History of Experimentation
Date Thu, 09 Oct 2014 16:02:28 GMT
THANK YOU!! Because I have no idea what "comp.lang.ada" is.


Valerie A. Mallder
New Horizons Deputy Mission System Engineer
Johns Hopkins University/Applied Physics Laboratory


> -----Original Message-----
> From: Tyler Palsulich [mailto:tpalsulich@gmail.com]
> Sent: Wednesday, October 08, 2014 9:34 PM
> To: dev
> Subject: Re: A Suggestion on Developing Documentation Based on the History of
> Experimentation
>
> For the lazy:
> https://groups.google.com/forum/#!topic/comp.lang.ada/oY_Qt3pUATM
>
> Have a good night,
> Tyler
>
> On Wed, Oct 8, 2014 at 9:30 PM, Bruce Barkstrom <brbarkstrom@gmail.com>
> wrote:
>
> > Already available on comp.lang.ada
> >
> > On Wed, Oct 8, 2014 at 9:01 PM, Lewis John Mcgibbney <
> > lewis.mcgibbney@gmail.com> wrote:
> >
> > > 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
View raw message