Documenting your network for fun and glory    

Producing documentation, the process of capturing and explaining one’s work for others to follow later, is felt by many in Information Communication Technology (ICT) to be a bane on all existence. No matter what you think of documentation, be it a necessary evil or an important part of running the ICT infrastructure, it’s a requirement—regardless of the size or complexity of your environment. Unfortunately, most often creating the documentation is left for those days when you have nothing else to do. When was the last time you had a day like that?

To help change that, to make creating the documentation easier and even more fun, this paper will provide you with key points and ideas to make your documentation meet and serve your needs.

The Approach
It is more fun and easier to start off with a clean slate. If your current documentation is out of date this is a great time to start fresh. Regardless, you can always work using the ideals I introduce here.

Step 1 – Standardization – Consistency for faster referencing
Design a template for the documents. Think this out before you get too far in to the work. Consider the different areas you need to have documented. When documenting your network and security environment, you’ll typically want to document the setup, connections and configurations of your existing network gear and servers, as well as your typical desktop deployments, specialty software and so on. Each of these areas will share common documentation requirements such as name, location, access IP address and so on.

Step 2 – Accessibility – Making your document useful to others when they need it most
Accessing the documentation is especially important in times of crisis. Consider what happens: Something isn’t working; it needs to be fixed fast. What does the documentation say? Well, it was stored on the server that we can’t access. Ooops. Storing the documentation on a network share may not be the ideal solution, even though it does allow for easy updating. You might find that printing your documentation monthly, and after a major revision, will provide a due balance between stored and printed data. Make sure to include date of revision and a version number on each page. Consider adding these as fields to your template.

Step 3 – Depth
How deep your documentation goes is typically a direct correlation to the complexity of the environment plus your tolerance for downtime. Deeper documentation will aid you more quickly in restoring services in the event of an outage. Depth means detail, and accurate detail means you can reestablish your configurations and connections more easily. The mandate of most IT departments is to deliver services and with better documentation complex environments can be recovered more quickly.

In summary, your 3 ideals are to standardize your documentation style, ensure it is accessible to your team in times of trouble, and that it provides sufficient depth of information to allow them to fix the problems.

Putting it all together
Serving your documentation up hot
If your ICT environment is larger than a breadbox, consider moving a good chunk of your documentation to a database, housed on your documentation server. You can custom build this in-house or use a pre-canned solution. Pre-canned solutions are available as free-ware and for purchase. Their advantage is that configuration details can be correlated and cross-referenced. Information is easily pulled from multiple areas to give a more accurate, real-time overview. The drawback is that if the documentation server is unreachable then it can no longer aid in trouble shooting a problem.

Include diagrams
For me as a network specialist the most important part of the documentation are the diagrams. Like the rest of the documentation the diagrams must contain enough detail to be useful. The caveat is to ensure you don’t include too much information – important parts can get lost. In complex environments a single diagram will prove too cluttered to be of any use. In such situations I recommend multiple device or system specific diagrams with an overview diagram showing how they relate. You can include separate diagrams based on specific services, purpose or area. Natural boundaries such as departments or geographical segmentation are great ways to determine how diagrams can be broken up. Remember a picture is worth a thousand words.

While a napkin or piece of paper is a romantic way to diagram your network it really lacks in flexibility, standardization and accessibility for collaboration. Microsoft’s Visio has long been the standard application for creating and maintaining network diagrams, and every major networking and security company provides custom device templates for you to use in it.

Food for Thought - More standardization
While you are designing your documentation system consider your device naming convention. Until virtualization, device naming was pretty simple. In an environment with multiple racks each rack is numbered, each rack has a limited number of rack units and only one device could occupy a rack unit. So an email server in the 3rd rack sitting at RU46 can be named mail-3.46. Now, with virtualization, your device naming needs to be thought through. This naming schema only applies to physical devices as the naming of virtual servers is a different game since they tend to float across various pieces of hardware.

As the complexity of your ICT environment grows so does the need for accurate documentation. Setting aside regularly scheduled time slots for documentation creation, review and updating becomes an important part of the IT department’s routine.

Orginally published Nov, 2011

PDF this Page
Fragment - Current Release


IT Roles and Responsibilities
On Passwords
Spending Enough
Planning to Fail
Living With the Enemy
A Reason for Policy
Mission Critical Messaging – Do you have a policy
Globalizing the SMB
High Availability: People and Processes
Case for Project Management
Risk Management

On Routing
VLAN Tutorial
IPs 4 Golden Rules
WAN Technology primer
DHCP Primer
Your Head in the Cloud(s)
DNS: Terms and Process
VPN Surfing Challenge
Network Slowdown
Importance of Time
High Availability: Technologies

Spammers Go Full Circle
Beyond the Lock
The Guardian at the Gate
A Web of Trust
Data Breach Notification

Electricity Primer
Data Control
Open Source in the Enterprise
Closing the Loop
Helping IT to help you
Your ICT Keystone

eSubnet Services

Contact us regarding your network,
security and Internet services needs

All content © eSubnet 2003-2021