A Suggestion on Developing Documentation Based on the History of Experimentation

[Bruce Barkstrom <br...@gmail.com>]

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.

RE: A Suggestion on Developing Documentation Based on the History of Experimentation

["Mallder, Valerie" <Va...@jhuapl.edu>]

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 <br...@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
> > > <br...@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*
> > >
> >

Re: A Suggestion on Developing Documentation Based on the History of Experimentation

[Tyler Palsulich <tp...@gmail.com>]

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 <br...@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 <br...@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*
> >
>

Re: A Suggestion on Developing Documentation Based on the History of Experimentation

[Bruce Barkstrom <br...@gmail.com>]

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 <br...@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*
>

Re: A Suggestion on Developing Documentation Based on the History of Experimentation

[Lewis John Mcgibbney <le...@gmail.com>]

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 <br...@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*

Re: A Suggestion on Developing Documentation Based on the History of Experimentation

["Mattmann, Chris A (3980)" <ch...@jpl.nasa.gov>]

Yes, I think an experience blog would be a great thing. So far we have
been trying to point people at the wiki to reduce the barrier for helping -
that may be a good path down what you¹re suggesting.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Chris Mattmann, Ph.D.
Chief Architect
Instrument Software and Science Data Systems Section (398)
NASA Jet Propulsion Laboratory Pasadena, CA 91109 USA
Office: 168-519, Mailstop: 168-527
Email: chris.a.mattmann@nasa.gov
WWW:  http://sunset.usc.edu/~mattmann/
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Adjunct Associate Professor, Computer Science Department
University of Southern California, Los Angeles, CA 90089 USA
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++






-----Original Message-----
From: Bruce Barkstrom <br...@gmail.com>
Reply-To: "dev@oodt.apache.org" <de...@oodt.apache.org>
Date: Monday, October 20, 2014 at 8:46 AM
To: "dev@oodt.apache.org" <de...@oodt.apache.org>
Subject: Re: A Suggestion on Developing Documentation Based on the History
of Experimentation

>I've been off for a week taking a break by avoiding e-mail and the news.
>
>However, I still did a bit of IT stuff by completing assembly of an Intel
>Atom by connecting a Solid State Drive and then installing Ubuntu Linux
>and
>AdaCore's
>GNAT GPL environment on it.  When I got home yesterday, I took some
>time to read through various e-mail exchanges on the comp.lang.ada site
>and found considerable frustration with what appear to be divergent
>package
>configurations between Linux distributors.  In other words, if you are
>willing
>to work within the packages provided by a particular distribution
>provider,
>software will probably work.  If you want to cross from one distributor to
>another, the cost of configuration management in both staff time and the
>money
>to pay for the staff can grow substantially.  That lesson got embedded in
>the documentation I did.
>
>I think there are probably several styles of understanding that need
>different kinds of documentation.  One is the "bottoms-up" approach
>that may just need man pages.  Another is a style that can use video
>clips in which people demonstrate and narrate a process.  A third is the
>style I seem to need.  That documentation needs lots of details, including
>the rationale for a procedure and ways of verifying whether it worked
>correctly.  There are probably others.
>
>A potentially (and sometimes actually) horrible form is misleading
>documentation.  The assembly instructions for the Atom had ten small
>photos
>showing how to remove the motherboard from the case, connect the
>components,
>and then how to reattach the motherboard.  The black-and-white pictures
>had
>brief Chinese phrases as well as English sound bites.  In reality, the
>computer
>was pretty much assembled - and just needed to have the Solid State Drive
>attached.  A stick-on label that was supposed to be attached to the case
>was too big to fit on the case without covering the opening for air
>circulation.
>
>Maybe the OODT site should open up an "experience blog" site that could
>provide raw material for eventually producing documentation that would
>reduce the user
>learning curve.
>
>Bruce B.
>
>On Tue, Oct 14, 2014 at 1:07 PM, Mallder, Valerie <
>Valerie.Mallder@jhuapl.edu> wrote:
>
>> Hi Bruce,
>>
>> I think you are right on target here.  You guys have created a huge body
>> of fantastic work, but no one is going to appreciate it if the learning
>> curve is too costly.  I have been keeping extensive notes on all of the
>> things I¹ve tried, all of the mistakes I¹ve made, and all of the
>> documentation I¹ve read that didn¹t lead me to where I wanted to go or
>>tell
>> me exactly what I needed to know for my situation.   I may write a white
>> paper on my on my experiences here, but if not, I will be happy to
>> contribute notes to this documentation effort if you it ever gets
>>started
>> and if you think they will be helpful.
>>
>> Thanks,
>> Val
>>
>> Valerie A. Mallder
>> New Horizons Deputy Mission System Engineer
>> Johns Hopkins University/Applied Physics Laboratory
>>
>> From: Bruce Barkstrom [mailto:brbarkstrom@gmail.com]
>> Sent: Wednesday, October 08, 2014 8:58 PM
>> To: dev@oodt.apache.org; Mattmann, Chris A (388J)
>> Subject: A Suggestion on Developing Documentation Based on the History
>>of
>> Experimentation
>>
>> 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.
>>

Re: A Suggestion on Developing Documentation Based on the History of Experimentation

[Bruce Barkstrom <br...@gmail.com>]

I've been off for a week taking a break by avoiding e-mail and the news.

However, I still did a bit of IT stuff by completing assembly of an Intel
Atom by connecting a Solid State Drive and then installing Ubuntu Linux and
AdaCore's
GNAT GPL environment on it.  When I got home yesterday, I took some
time to read through various e-mail exchanges on the comp.lang.ada site
and found considerable frustration with what appear to be divergent package
configurations between Linux distributors.  In other words, if you are
willing
to work within the packages provided by a particular distribution provider,
software will probably work.  If you want to cross from one distributor to
another, the cost of configuration management in both staff time and the
money
to pay for the staff can grow substantially.  That lesson got embedded in
the documentation I did.

I think there are probably several styles of understanding that need
different kinds of documentation.  One is the "bottoms-up" approach
that may just need man pages.  Another is a style that can use video
clips in which people demonstrate and narrate a process.  A third is the
style I seem to need.  That documentation needs lots of details, including
the rationale for a procedure and ways of verifying whether it worked
correctly.  There are probably others.

A potentially (and sometimes actually) horrible form is misleading
documentation.  The assembly instructions for the Atom had ten small photos
showing how to remove the motherboard from the case, connect the components,
and then how to reattach the motherboard.  The black-and-white pictures had
brief Chinese phrases as well as English sound bites.  In reality, the
computer
was pretty much assembled - and just needed to have the Solid State Drive
attached.  A stick-on label that was supposed to be attached to the case
was too big to fit on the case without covering the opening for air
circulation.

Maybe the OODT site should open up an "experience blog" site that could
provide raw material for eventually producing documentation that would
reduce the user
learning curve.

Bruce B.

On Tue, Oct 14, 2014 at 1:07 PM, Mallder, Valerie <
Valerie.Mallder@jhuapl.edu> wrote:

> Hi Bruce,
>
> I think you are right on target here.  You guys have created a huge body
> of fantastic work, but no one is going to appreciate it if the learning
> curve is too costly.  I have been keeping extensive notes on all of the
> things I’ve tried, all of the mistakes I’ve made, and all of the
> documentation I’ve read that didn’t lead me to where I wanted to go or tell
> me exactly what I needed to know for my situation.   I may write a white
> paper on my on my experiences here, but if not, I will be happy to
> contribute notes to this documentation effort if you it ever gets started
> and if you think they will be helpful.
>
> Thanks,
> Val
>
> Valerie A. Mallder
> New Horizons Deputy Mission System Engineer
> Johns Hopkins University/Applied Physics Laboratory
>
> From: Bruce Barkstrom [mailto:brbarkstrom@gmail.com]
> Sent: Wednesday, October 08, 2014 8:58 PM
> To: dev@oodt.apache.org; Mattmann, Chris A (388J)
> Subject: A Suggestion on Developing Documentation Based on the History of
> Experimentation
>
> 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.
>

RE: A Suggestion on Developing Documentation Based on the History of Experimentation

["Mallder, Valerie" <Va...@jhuapl.edu>]

Hi Bruce,

I think you are right on target here.  You guys have created a huge body of fantastic work, but no one is going to appreciate it if the learning curve is too costly.  I have been keeping extensive notes on all of the things I’ve tried, all of the mistakes I’ve made, and all of the documentation I’ve read that didn’t lead me to where I wanted to go or tell me exactly what I needed to know for my situation.   I may write a white paper on my on my experiences here, but if not, I will be happy to contribute notes to this documentation effort if you it ever gets started and if you think they will be helpful.

Thanks,
Val

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

From: Bruce Barkstrom [mailto:brbarkstrom@gmail.com]
Sent: Wednesday, October 08, 2014 8:58 PM
To: dev@oodt.apache.org; Mattmann, Chris A (388J)
Subject: A Suggestion on Developing Documentation Based on the History of Experimentation

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.