Home > Articles

Documentation: Your Essential Discovery Tool

📄 Contents

  1. Navigating a Bad Network Neighborhood
  2. Documentation Dividends
  3. Summary
  4. Q&A
  5. Workshop
  • Print
  • + Share This
This chapter is from the book

I am always at a loss to know how much to believe of my own stories.

—Washington Irving, Tales of a Traveller

Would you start out on a car trip in a strange country without a map? Would you simply presume that you'll figure it out when you get there? Of course you wouldn't, but this is what people do every day when they fail to document their ever expanding networks.

When it comes time to troubleshoot, those who don't have a map to go by just shrug and shake their heads. Undocumented networks are mostly in-comprehensible. You need some method of getting your bearings, and network documentation can be an invaluable compass in what can be a sea of confusion.

This goes for an existing network as well as for one that you are just building. "As you build it, so shall it be," to quote one of my mentors. That is, if you build a network without documenting it for your future self, expect your future self to be befuddled, asking, "What exactly did my past self do here?" Networks are complex beasts by nature. And there is no such thing as a network that doesn't grow.

As such, it's absolutely essential that you and others who work on your network have some sort of well accepted rules (standard operating procedure, or SOP, to use the industry term) that dictate how and when you document. Just as no traditional job is finished until the paperwork is done, no network upgrade or addition is complete until the documentation is done. Documentation can include anything from logs and lists to charts and diagrams. It's anything that will make your life easier in the future.

You and your peers are not the only people who document your network, of course. Although you're the only folks who can document the way that your network is put together, it's worth your time and effort to completely read product documentation before deploying. It's amazing how many misconfigured (and thus malfunctioning) networks you will see with the simple problem that the implementers did not read the product documentation. Some problems are resolved, as they say out on the Net, by "RTFM" (Read The Fabulous Manual). (See Hour 6, "The Sesame Street Method: Using What Works," for more on vendor-supplied information.)

Navigating a Bad Network Neighborhood

Some people will tell you that complete documentation is too much trouble, or that it takes too much time and doesn't buy you all that much. This is utter hogwash. (Although many gray areas exist in network troubleshooting, this is one issue that is definitely black and white.) Folks without documented networks are the ones running around with their hair on fire; those with documented networks have fixed the problem, gone to lunch, done something productive, and gone home to spend time with their kids. This might sound rather judgmental, but too much evidence suggests that either you document once and have a reference during times of trouble or you fail to document at all and end up having to figure out something multiple times: once during each crisis.

For example, let's say that your wiring closet isn't labeled at all. Without documentation, if you are having a problem with a certain PC and want to check the switch port, you'd need to spend anywhere from 5 to 15 minutes tracing the cable from the workstation to the closet switch. Now multiply this by the many potential workstation cable problems that you'll see in your lifetime as a troubleshooter, and the amount of wasted time becomes horrific.

Not only does insufficient documentation waste time when your network is having problems, but it also causes unnecessary fear and confusion during the crisis . You owe it to yourself to have as clear a situation as possible when you start to troubleshoot—believe me, there's enough uncertainty and doubt when you're trying to find your way out of a bad network neighborhood without adding to it due to a lack of a good map.

  • + Share This
  • 🔖 Save To Your Account