On Thu, Jun 17, 2010 at 5:21 PM, Mark Dennehy <mark.denn...@gmail.com>wrote:
> On Wed, Jun 16, 2010 at 2:39 AM, Damion Alexander > <dam...@damion-alexander.com> wrote: > > If you were in this situation, on either side, what would you expect in > that in-house documentation? > > Well... > > _Why_ the system is set up the way it is (how is easy, why isn't) > ... What your roadmap was for the development of the system architecture > and what your rationale was, and contingencies for things like budget > cuts or sudden ramp-ups in demand > I wrote a piece about this very issue for ;login: a few years ago, titled "What are your intentions?" ( http://www.usenix.org/publications/login/2001-07/pdfs/chapman.pdf). Here are the first few paragraphs: Air traffic controllers, with their ability to use radar to see exactly what aircraft are doing, seem to be the very picture of omniscience in their domain (at least until the 30-year-old mainframe in the basement blows another vacuum tube, and the whole screen goes blank). However, there's a big difference between "all-seeing" and "all-knowing." A controller might be able to see exactly what a given aircraft is doing, but be totally in the dark about whythe aircraft is doing that. If the controller doesn't know and can't figure it out, the pilot of the aircraft in question soon hears something like "Cessna Four Three Zero Papa, what are your intentions?" The controller needs to know what each of the pilots in their care is trying to accomplish, so that the controller can coordinate all their actions to get them each safely and efficiently to their destinations. Whether we realize it or not,as IT professionals we often face similar situations. Any competent system administrator can examine a system and determine the details ofhow the system is configured, but they may still be totally in the dark about why it is configured that way. Without understanding the "why" behind a system's configuration, it's much more difficult to make changes or updates to the system successfully, because it's much more difficult to predict the effects (positive or negative) that those changes will have. It's also difficult to evaluate how well a system is currently doing its job, when you're not entirely sure just what job it was designed to do. When documenting our systems and networks, we often spend a huge amount ofeffort documenting what they are, how they're configured, and how to use them, but little or no effort documenting why we set them up that way. While a certain amount of "what" and "how" documentation is definitely called for, particularly as a map of the situation, there are two problems with producing only this form ofdocumentation. First, much of this documentation quickly gets out ofdate, particularly if it covers system-level details like how much memory and disk space a system has; when you need to know such info, it's usually better to get it from the system directly. Second, even if it's kept accurate, this documentation doesn't tell a later reader (months or years after the system was deployed) anything at all about _why_ the system is configured that way, which makes it more difficult to repair, extend, replace, or retire. -Brent -- Brent Chapman <br...@netomata.com> Netomata, Inc. -- www.netomata.com Making networks more cost-effective, reliable, and flexible by automating network configuration
_______________________________________________ Discuss mailing list Discuss@lopsa.org http://lopsa.org/cgi-bin/mailman/listinfo/discuss This list provided by the League of Professional System Administrators http://lopsa.org/
