[Scribia-dev] Uhoh... we better write docs...

[Ben H. <bh...@sa...>]

RISKS-Digest rules.

At 4:08 PM -0700 6/13/01, RISKS List Owner wrote:
>Date: Fri, 8 Jun 2001 14:59:11 -0500
>From: "Dankmyer, Kirt" <Kir...@cs...>
>Subject: Dead men produce no documentation
>
>I was recently assigned to take over a system that processes and sends data
>to a wide variety of scientific agencies that depend on said data. In
>particular, I've been asked to understand the system well enough to maintain
>and troubleshoot it.
>
>Naturally, the system, both software and hardware, was created "in-house" by
>contractors. Nothing like anything I'd experienced before. When I requested
>documentation, I was told there was none. The last person who had to work on
>the system had produced a draft of user documentation, but it was
>incomplete.
>
>So, I contacted the poor soul who had worked on this system before me, the
>one who had produced the incomplete documentation. (We'll call her Joan.)
>Joan was only familiar with the part of the system she had worked on (the
>user interface, really). So I asked her about the two people who had
>designed and implemented the system in the first place. I thought that they
>could perhaps help me with some of the questions I had.
>
>One of them had left the company that originally employed her, and wouldn't
>return phone calls. So I asked Joan about the other designer, who seemed to
>have done the bulk of the work anyway.
>
>"He's dead," Joan told me. "Heart attack."
>
>The risk? If you skimp on documentation while designing a custom system, you
>may find that you don't have time to go back and do it later, with serious
>consequences for those who follow you. This problem should be familiar to
>most readers of RISKS, but it bears repeating. As I write this, a problem
>has come up with the system and no one is even sure if it is hardware or
>software. When dealing with such a system, you cannot guarantee you will be
>able to talk to the original designer (and the only one who understands the
>system fully), and it might be because they've left more than just the
>company that originally produced the equipment. Sic transit gloria mundi...
>
>Kirt Dankmyer -- 757-824-2283 -- kir...@cs...
>CSOC UNIX System Administrator -- Wallops Flight Facility
>
>   [Of course, Wallops Island is where a lightning strike hit the missile
>   launch platform when a missile was waiting to be launched to test the
>   effects of lightning -- and resulted in the missile accidentally being
>   launched.  PGN]
-- 
NOTE: Please change my address in your address book from bhines at san.rr.com
to bhines at alumni.ucsd.edu as my UCSD address will be permanent.
<http://freepages.sf.rootsweb.com/~bhines/> - My Genealogy Pages