For more IT articles and tips specific to small and midsized businesses, visit SearchSMB.com.
When most administrators -- especially those in small to medium-size businesses -- think of "documentation", we think mostly of a diagram, usually in Visio, that
Requires Free Membership to View
depicts how servers and routers and switches are connected either logically or physically. Documentation might also include circuit IDs, names and phone numbers of people to call in an outage and other similar instances. In a nutshell, this is the "who, what, when, where" documentation.
Unfortunately, that's about all the documentation that is kept. Notably missing, and critically important is the "why". Well, you think, if you haven't been documenting the "why" for all these years, it can't be that vital, can it? Consider this common scenario:
You make some architectural decision, which makes lots of sense at the time. Over time, the environment changes a little here, and a little there, so that your decisions are no longer optimal. You then get promoted, and your new replacement is evaluating your work. If you've been on either side of this situation, you know that the replacement will evaluate the design based on the environment TODAY, and not the environment when it was designed. If you haven't documented why you made the decisions you did, it will look like you are a very poor decision maker.
When you document the "why", be sure to answer the following questions:
What decision did you make and when did you make it?
What constraints played a factor?
What assumptions played a factor?
What alternatives did you consider, and why were they not selected?
Keeping the answers to these questions in a repository where you can quickly look them up and understand them will not only help future generations of network administrators avoid landmines, but over time, it will also help you understand how you make decisions, and how your choices turned out, and thus, help you make better decisions in your own future.
Tom Lancaster, CCIE# 8829 CNX# 1105, is a consultant with 15 years experience in the networking industry, and co-author of several books on networking, most recently, CCSPTM: Secure PIX and Secure VPN Study Guide published by Sybex.
This was first published in December 2004