oodt-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bruce Barkstrom <brbarkst...@gmail.com>
Subject A Suggestion on Developing Documentation Based on the History of Experimentation
Date Thu, 09 Oct 2014 00:57:40 GMT
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.

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