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: [email protected] 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 <[email protected]> Reply-To: "[email protected]" <[email protected]> Date: Monday, October 20, 2014 at 8:46 AM To: "[email protected]" <[email protected]> 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 < >[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. >>
