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 brbarkstrom@gmail.com
 designates 209.85.212.170 as permitted sender)
MIME-Version: 1.0
Date: Wed, 8 Oct 2014 20:57:40 -0400
Message-ID: 
 <CAOG8ptVZM64aCxvEJUGHexJtmSN0+5E1EWVOvV=vLOwHnBeeRA@mail.gmail.com>
Subject: A Suggestion on Developing Documentation Based on the History of
 Experimentation
From: Bruce Barkstrom <brbarkstrom@gmail.com>
To: dev@oodt.apache.org,
	"Mattmann, Chris A (388J)" <chris.a.mattmann@jpl.nasa.gov>
Content-Type: multipart/mixed; boundary=047d7b86e1ec5b04700504f2eb25

--047d7b86e1ec5b04700504f2eb25
Content-Type: multipart/alternative; boundary=047d7b86e1ec5b04690504f2eb23

--047d7b86e1ec5b04690504f2eb23
Content-Type: text/plain; charset=UTF-8

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.

--047d7b86e1ec5b04690504f2eb23
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div><div><div><div><div><div><div><div><div><div><div><di=
v><div><div><div><div><div><div><div><div><div><div><div><div>During the la=
st month, I managed to get a fairly difficult installation task<br></div>to=
 work on software I felt I had a critical need for.=C2=A0 I&#39;ve attached=
 the<br></div>documentation I wrote as I went through the experience descri=
bing<br></div>what I had to do.=C2=A0 I think we often denigrate writing do=
cumentation at<br>the level of detail in the attached document as dealing w=
ith &quot;newbies&quot;<br></div>who are a bit below our level of disciplin=
ary attainment.<br><br></div>Based on my experience, it&#39;s more appropri=
ate to regard the documentation<br>as showing the kind of professional leve=
l of instructions surgeons exhibit<br></div>when they write down a procedur=
e for other surgeons to learn how to do.<br></div>We don&#39;t think surgeo=
ns should write down what they&#39;re doing in a one page<br></div>summary =
intended for managers.=C2=A0 Managers don&#39;t have the training to know<b=
r></div>what kind of stitches to make that will hold a suture against a sur=
ging artery.<br></div>If you ever have to have surgery (or have a person yo=
u care for undergo<br></div>surgery) you want that surgeon to know the deta=
ils of what he or she is<br></div>doing, to understand the risks of the pro=
cedure, to have plans for dealing<br>with the most common exceptions, and t=
o close up the wound without<br>losing things.=C2=A0 This isn&#39;t work fo=
r &quot;newbies&quot; -- it&#39;s a professional commitment<br>we make to t=
ry to pass on what we&#39;ve learned so people coming after us<br>don&#39;t=
 have to work so hard and make as many mistakes as we did.<br><br></div>I t=
hink it would be helpful to take the exception handling procedures we&#39;v=
e<br>had to go through with Valerie and other folks on OODT and use the rec=
ord<br></div>(in e-mail and maybe elsewhere) to write up a professional sum=
mary of the<br></div>procedures an inexperienced OODT user would have to fo=
llow to successfully<br>install OODT and get it to work.=C2=A0 I didn&#39;t=
 enjoy working through the rationale<br></div>for why you couldn&#39;t just=
 rely on the Debian Linux packages for the AdaCore<br></div>GNAT GPL instal=
lation.=C2=A0 The same thing is true of the CAS PGE Crawler task.<br><br></=
div>It is absolutely critical to help new (and even experienced) users navi=
gate<br></div>the treacherous path from starting out to successful and (rel=
atively) error<br>free operation.=C2=A0 The success of other folks in insta=
lling OODT is going to <br></div>depend on getting the maintenance cost dow=
n to the LOCKSS level of<br></div>a person-hour per month.<br><br></div>Let=
&#39;s see what we can do to make this happen.=C2=A0 If we can, OODT will b=
e<br></div>a singular example.=C2=A0 If we do, it won&#39;t be luck, it&#39=
;ll be the really hard work<br>we put in.=C2=A0 Our reward will be clear an=
d it won&#39;t depend on how many grants<br>we get or how many NASA medals =
we earn.=C2=A0 We&#39;ll know it - and that will suffice.<br><br></div>Bruc=
e B.<br></div>

--047d7b86e1ec5b04690504f2eb23--

--047d7b86e1ec5b04700504f2eb25--