The Importance of Documentation

Unless you were lucky enough to build your network from the start, chances are that you inherited an "organically grown" network. Perhaps different independent networks were built years ago and subsequently connected to the corporate net, or different organizations have had control over parts of the network and turned over their control to your organization. Or perhaps your group has grown the network over the years but has not documented the changes. However your network has grown, trying to manage it without understanding where devices are and how they're connected can be extremely difficult.

Documenting and tracking the physical inventory and logical connectivity will not only simplify the task of implementing effective network management, but it will also greatly enhance the timeliness of problem resolution. With the network being the backbone of corporate data exchange, your group's timeliness in resolving network problems has the ability to affect the enterprise's bottom line.

If a financial firm loses the capability to trade stocks due to a network outage, not knowing where network devices are located and how they are connected ultimately translates into lost revenue for the company. Do you know how much money per hour of downtime your company loses with unplanned outages?

Documentation can be maintained on anything from scraps of papers and napkins to intricate database systems. Ultimately, however it's maintained, the documentation should communicate its contents clearly and should easily be shared by those who need the information. It must also be easy to update and modify by those who need to.

The ultimate test is at 3 a.m. when you are paged out of bed to determine why several buildings dropped off of the network. If you find yourself tracing cables and wondering whether a router is connected to the right switch despite your documentation, perhaps it is time to reconsider your documentation practices.

Please see Chapter 9, "Selecting the Tools," for more details on criteria for tools that can help you with documentation.

TIP

Effective and reliable documentation must contain the following traits:

• A consistent and integrated method for storing information, such as a database or spreadsheet.

• Non-intrusive processes surrounding the maintenance of the documentation. If the docs are too difficult to keep up-to-date, the documentation will be rendered useless.

• Easy online access to the documentation for those who need it. This includes viewing as well as updating the documentation.

• Automation (self-documenting) whenever possible. Automated data collection helps you keep your documentation up-to-date.

• Port standardization and interface description usage (discussed later in this chapter).

It is important to determine the usefulness of each form of documentation and compare it to the organizational cost (that is, the difficulty in maintaining it). Sometimes, organizations can get documentation paralysis in which the maintenance of a particular piece of documentation overweighs its usefulness. It tends to be a matter of trust with documents because after the users of a particular document or knowledge base find that the information is out-of-date or wrong, they lose trust for the information. And after a couple of attempts that result in the discovery of out-of-date information, the documentation will no longer be used.

Ultimately, there is a natural balance. Too much documentation is difficult to maintain and becomes useless. Not enough documentation results in not having information when you need it.

Part of maintaining accurate documentation is implementing automated methods for updating the information. For instance, in a network made up of Cisco devices, you can automatically discover and track physical connectivity between routers and switches by using the Cisco Discovery Protocol (CDP). Or, the location of Media Access Control (MAC) addresses can be tracked by querying the Content-Addressable Memory (CAM) tables from the LAN switches.

Unfortunately, there are preciously few tools that take advantage of this information to produce a Layer 2 topology. The CDP and CAM tables are available via SNMP, enabling you to build your own applications.

Some things cannot be automated, such as physical wiring termination. For those that cannot be automated, you should work to integrate the documentation of a change into the overall process of making the change.

Take the running of new cables between wiring closets as an example. As part of running the cables, labels that identify the source and the destination of the run should be created and attached to the wiring racks. In addition, labels that identify either end should be attached to the cables themselves.

Whenever a connection is physically modified, the change should be indicated in a knowledge base, which is discussed in Chapter 3, "Developing the Network Knowledge Base." Thus, the database becomes the source of connection information.

TIP

Following are some tips on tracking and documenting moves, adds, and changes. Although these tips describe the best possible tool scenario, they should be used as goals when building and buying software:

• Make changes electronically in a method that allows the change to be automatically documented when the change occurs. Examples include activating a previously unused switch port or switching a user to a different VLAN, and capturing the changes through syslog messages and SNMP traps.

• Integrate the change tools so they populate the knowledge base automatically.

• Integrate the change tools with a change management tool so overlapping or competitive changes are regulated and documented appropriately.

• Make sure that configuration changes can be tracked and logged. Using tools that track user configuration changes and enforce configuration policies will help you prevent and/or track unauthorized and mistaken changes.