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:[email protected]] > 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 <[email protected]> > wrote: > > > Already available on comp.lang.ada > > > > On Wed, Oct 8, 2014 at 9:01 PM, Lewis John Mcgibbney < > > [email protected]> 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 > > > <[email protected]> > > > 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* > > > > >
