When it comes to network documentation I sometimes feel like justice Potter Stewart, referring to the threshold test for obscenity: “I know it when I see it”.

Organizations come in many shapes and sizes, engineers can be very creative under tight budgets, and everybody has a different way of tackling a problem, so when you read the opinions of the network documentation intelligentsia you’ll encounter a myriad of tools and processes used out there. They rarely seemed satisfied with the end product though, and just like with DCIM, if you ask 10 engineers what exactly network documentation is, you’ll get 11 answers (or maybe 17). So I thought, why don’t we start by weeding out what does NOT constitute a network documentation tool?

A wish list

Before we dive into the meat of the blog title, we still have to analyze what we would like to have in our network documentation. This would be my wish list:

• Geographical hierarchy with related information: sites, buildings, floors, rooms and so on
• Rack elevations with device make and model information and their properties
• Cabling infrastructure, ideally port-to-port
• Topology views with layer 1 to 3 core and access devices and circuits
• Customizable nodes, links and fields: there is more to IT inventory than blob-like routers with an IP address, you know
• Supporting documents: config files, firewall rules, access control mechanisms, processes and procedures, etc.

It’s not just about the ‘what’ though. There are also requirements on how you gather the data, who accesses it, and how useful it is.

• Visual diagrams: Network documentation is more than just data and words in some document or spreadsheet. We are not psychologists here trying to talk them networks out of an outage for crying out loud! You can depict connectivity, hierarchy, relationships, states and properties much better pictorially than with mind numbing reports, rows and columns. Engineers are visual people.
• Automation: you want to reduce the manual effort as much as possible, for example by discovering elements via SNMP. Also, if you already have stuff in other systems like a CRM, an Asset Management tool or your own home-grown database, your network documentation tool should be able to bring that in as well.
• Flexibility: you want to document the network the way you want it, with the properties you need and the hierarchies and entities relevant to your organization.
• Accessibility: maybe it is me, but I would like a tool that can be easily accessed by the appropriate stakeholders. In my book that means: web-based and with granular, role-based security access controls.
• Easy-to-use: probably the most overlooked aspect when testing enterprise software is the usability. If your system is complicated, it will gain no adoption and will become out-of-date in no time.

Now, on to the party-pooping exercise.

Your monitoring/NMS tool is not your network documentation

I’ve heard it way too often: “yeah, we use our network monitoring tool for documenting the network”. If that’s what you do then I am sorry to tell you:

Donny, you’re out of your element.

If you use your NMS as your network documentation system, your diagrams will be missing quite a few details. For starters, monitoring tools only bring in whatever they discover. How about devices from other vendors, patch panels, non discoverable elements, or devices using other protocols, dumb boxes, racks, industrial equipment, cabling, and so on? NMS tools are also usually not accessible for large parts of the organization, not very easy to use and have not much of a physical depiction of assets (let alone DCIM related features).

And how about the diagrams themselves? Check out the thumbnail on your right and see what passes for IT visualization with some of the usual suspects of the NMS club. Good grief. I think you get the picture (well, actually you don’t <grin>).

AutoCAD, Wiki, SharePoint, Google Docs and other eclectic adventures

Oh, I am sure you can manufacture some clever stuff using a wiki. I have also seen lots of great collaboration using SharePoint or Google Drive. You can create some of the most detailed diagrams with AutoCAD too. Problem is your name is not Tatsuo Horiuchi.

Tatsuo is a 73-year old Japanese artist that can turn an Excel spreadsheet into beautiful art. It is really amazing, clever and highly unorthodox. Kudos to him, but most of us do not have the talent and patience to do something like this. More importantly, we are usually not documenting networks for fun, and we always lack the time to do it.

If I had a nickel for every time I hear somebody say “oh, I can also do <task>, using <a bizarre tool>”… I’ve heard of a guy that uses the recycle bin as a file storage system. And you probably heard the story about the lady using the CD-ROM drive as a cup holder. Heck, even extreme nerds have this tendency. I knew a programmer that refused to use an IDE and instead wrote all the code in notepad. Just because you can doesn’t mean you should.

If your network is tiny, I get it. A wiki or a spreadsheet may be fine. You may not need diagrams; rows and columns could be all you need. You may not need the automation. But if you are trying to keep up with daily changes of a 100+ node corporate network automation becomes key.

So, in sum:

With the “monitoring as documentation” philosophy, you get the automation, but you miss a ton of configuration items, diagrams and other features. With the group of “eclectic tools” you get the flexibility you need, but you will have a collection of point products designed for something else and little to no automation.

Whether it is netTerrain or some other product, this Christmas do yourself a favor: instead of asking Santa for a pony, get yourself a real network documentation system.

Jan