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 < [email protected]> 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:[email protected]] > Sent: Wednesday, October 08, 2014 8:58 PM > To: [email protected]; 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. >
