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*
