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* >
