Networking

How to tackle a network documentation project

Few IT tasks are more tedious than network documentation, and the job becomes especially challenging when you have to build it from scratch. These pointers will help you get your documentation project on the right track.


Maybe you've walked into a new network administrator position only to find that no documentation exists for the network. Or maybe your boss just called you in and said, “I want you to document our network from the ground up.” Regardless of the situation, if you have to document a network that has no existing records, it's hard to know where to start. To help you figure out your game plan, this article will show you:
  • How to determine what network information to document.
  • How to gather the information you need.
  • How to best present that information.

Let's look first at what makes all this effort worthwhile.

Why document?
You may be wondering why you're expected to spend precious time on documentation when you're already swamped with tasks like performing routine maintenance on servers and switches, responding to network problems, planning and performing upgrades, and attending endless meetings. The fact is that there are a number of compelling benefits to having a well-documented network. Your documentation can be:
  • An aid to troubleshooting—When something goes wrong, the documentation will serve as a handy reference to guide the troubleshooting effort. It will save time and money.
  • An aid to training new personnel—If a new person comes on board, he or she will get up to speed much faster if a printed reference is available. It will save time and money.
  • An aid to contractors and consultants—These people are expensive. If they need to know the details of the network infrastructure, they will proceed much faster if documentation is available. That will save the company time and money, which the boss will appreciate very much.

Sounds like a plan
Like any major project, documenting your network will require some planning. It is important to remember that this is primarily a communications project. It is going to be your job to take technical information about a given network and present it to someone less familiar with that network in a way that allows the person to know what you know. During the planning phase, you must decide what to document, where to get the information you need, and how to present it.

What to document?
If you were taking over a network for the first time, what information would you want to know about it? That is what you should document for your network. Provide the information in a form that is both clear and useable and that will be available when those who have the institutional knowledge are not. That is what documentation is all about.

You also need to set the priorities for your documentation. Decide what information you need to record right away and what information can wait until later. You can’t do it all at once.

Although every network has its own unique features, many common elements are candidates for documentation. These include:
  • Network topology—This is usually done in the form of a diagram that shows the major network nodes, such as routers, switches, firewalls, and servers, and how they are all interconnected. Normally, printers and workstations are not included.
  • Server information—This is all of the information on servers that you will need to manage or administer them, such as name, functions, IP address, disk configuration, OS and service pack, date and place of purchase, warranty, and so forth.
  • Router and switch port assignments—This includes detailed information on WAN configuration, VLANs, or even the assignment of a port to a network node via the patch panel.
  • Configuration of network services—Network services, such as DNS, WINS, DHCP, and RAS, are critical to the operation of the network. You should describe in detail how they are structured. Although it would be possible to derive that information by inspecting the servers, the point is to save that time by having it documented in an easy-to-decipher format.
  • Domain policies and profiles—You can restrict the capabilities of network users with the Policy Editor in Windows NT or with Group Policies in Windows 2000. You can also create roaming profiles that are stored on a server rather than on local machines. This kind of configuration, if used, should be documented.
  • Mission-critical applications—You must document how these are maintained, as well as what typically goes wrong with them and how you resolve problems.
  • Procedures—This in itself can be a major undertaking. Procedures are basically the means by which we carry out policies, and they can be quite extensive. For instance, a policy can state, “The network shall be secure against unauthorized users.” However, it takes a great deal of effort to implement that policy. There are procedures for the firewall, for network protocols, passwords, physical security, and so forth. You would probably also have procedures for dealing with problems that are reported by users and for routine maintenance of the servers.

Where do you get the information?
If you're documenting a network you administer, you probably know more about that network than anyone else. Even if the information that needs to be documented isn't in your head, you probably know how to track it down. But if you are asked to document someone else’s network, either as a new supervisor for the network support staff or as a consultant, you can't rely on your own knowledge. To gather the necessary details, you'll have to interview all of the other administrators extensively.

Getting the information you need from the administrators might not be easy. For one thing, political factors can thwart your efforts. It may be that an administrator resents you, seeing you as an “outsider.” It may be that an administrator feels threatened by the documentation project or feels that documentation is unnecessary. In these cases, you will need all the skills of a diplomat to extract the necessary information. You will have to find a way around these obstacles. Maybe you'll be able to make the administrators see that they're an important part of the project.

Even when administrators are willing participants, you may run into problems communicating with them. Many times, people will overlook matters that they see as obvious, but are far from obvious to someone else. Or they may be perfectly capable of performing their job, but lack the skills to describe it to others. You will need to be both patient and tenacious in talking with the other administrators, often approaching the same problem from different directions to get the needed information. And you'll still probably have to do some investigating on your own.

If you are hired in at the level of senior network administrator, and the previous administrators left no information behind—and no knowledgeable staff members are available—you will need to seek the information you need from the network itself. This will involve tracing cables, accessing server configurations and router/switch configurations, and so forth.

How do you present the information?
Once you get all the information you need, you must find a way to communicate it to others as effectively as possible. True, you could write it all down in narrative form using a word processor such as Microsoft Word, but it would be tedious to read. As with most technical material, it may be better to provide at least some of the information in graphic form. In other cases, the information might best be presented in tabular form, as with a spreadsheet. The point is to communicate as effectively as you can, using whatever tools are necessary.

One of the most effective tools for graphically presenting network information is Microsoft Visio, which allows you to quickly drag and drop network components, such as servers and switches, into your drawings. Figure A shows a simple example. In the case of processes or procedures, you could present the information as a flowchart, using Microsoft Visio or another flow-charting program.

Figure A


Table A shows some tools that may be helpful in documenting various aspects of your network.

Table A
Tool Purpose
Graphics program Systems overview
Network topology
WINS replication partners
Switch port assignments
Printer locations
Workflow (some procedures)
Spreadsheet Server documentation
Workstation documentation
Maintenance schedule
Word processor Procedures
System descriptions

The payoff
Although it can be a time-consuming job, documenting your network is important and necessary. Take the time to properly plan your documentation project. Consider not only what aspects of your network you will need to document, but also in what priority. Carefully plan how you intend to acquire the information you need and how you are going to present the information once it is gathered. You'll realize the payoff for your hard work when the time comes to troubleshoot problems, train new hires, and outsource tasks.

Editor's Picks

Free Newsletters, In your Inbox