Network documentation is one of those things that people struggle to accurately label and describe. In the same way that art is in the eye of […]

The Gloves-Off Approach to Defining Network Documentation: What It’s Not

Network documentation is one of those things that people struggle to accurately label and describe. In the same way that art is in the eye of […]

0
0

Network documentation is one of those things that people struggle to accurately label and describe. In the same way that art is in the eye of […]

By Jan Durnhofer
In Cloud Network Documentation
March 22, 2017


Network documentation is one of those things that people struggle to accurately label and describe. In the same way that art is in the eye of the beholder, so too is network documentation.

In fact, the need for proper network documentation can bring out the artist in all of us. Engineers tend to get creative under budget restraints, and just as there are as many ways to tackle a problem as there are people in the world there almost as many different network documentation processes and solutions. There is, however, one common element: end-result satisfaction is rare.

Similar to DCIM, ask ten different people to define network documentation and you will end up with at least ten different answers (more like 15 or 20 answers). One effective way to define something is to eliminate things from its definition. To define network documentation, let’s weed out what it’s not.

What Do We Want? Properly Documented Networks! When Do We Want It? Now!

Let’s back up a bit before we start eliminating. Here’s a look at a basic wish list for network documentation (this will probably vary a little depending on your unique needs):

  • Hierarchy – and all relevant info: rooms, floors, buildings and sites (etc)
  • Rack elevations (alongside device make and model properties and info)
  • Port-to-Port Cabling Infrastructure (ideally – but if not, at least basic cabling infrastructure)
  • Topology Views: Layers 1 to 3 (with core and access circuits and devices)
  • Nodes, links and fields that can be customized (because, as we all know, there is more to your IT inventory than red icons with an IP address)
  • Access to all relevant documents: configuration files, access control mechanisms, firewall rules, processes, procedures and so forth.

So, above is my wish list for the “what”. It’s not JUST about the what, however. It’s also about the HOW: how the data is gathered, how it is accessed and how useful it ultimately is.

  • Visual: you need to have visual diagrams. Why? Network documentation goes well beyond just the data and words on an Excel sheet. Words are fine and good but…let’s face it: we’re not PhD-wielding therapists trying to talk our networks down from the outage ledge. Diagrams depict hierarchy, the relationships, how everything is connected, properties and current states much more effectively – and without the yawn-worthy columns and rows we’ve all come to hate in spreadsheets. After all, engineers are very much visually-oriented people.
  • Automate: you need to limit the amount of manual effort whenever you can (such as through discovery via SNMP). If you already have information in systems such as your own home-grown database, a CRM or asset management solution, your network documentation should be able to discover that for you.
  • Flexible: you shouldn’t have to work around the tool, the tool should work around your processes. You need to be able to document your network the way you want to – with the properties you need and the entities and hierarchies that are most relevant to your unique organization.
  • Accessible: your tool should be easily accessible by all appropriate stakeholders. What does that mean? Granular, role-based security access controls in place and web-based.
  • User-friendly: often overlooked but always important…usability is key when it comes to testing enterprise-grade software. A complicated system doesn’t become easier with time: it becomes shelfware.

So, now that we’ve covered what is needed and how, we’ve got to bring out the bad news (sorry)…

That monitoring/NMS tool? That is NOT network documentation.

We’ve heard it time and time again…”well, to document the network we actually use our network monitoring tool.” If that’s what you’re using, here’s the bad news:

You are out of your element.

Using your NMS as your primary network documentation system means your diagrams will be sorely lacking. Monitoring tools, after all, can only include what they can discover. You’re missing devices from other vendors, non-discoverable objects, cabling, racks, patch panels, industrial equipment and much more. Further, your NMS tool is not accessible for all of your stakeholders, it’s not easy to use and doesn’t offer much of a physical depiction of your assets.

Bill & Ted’s (Not So) Excellent Adventure Through GoogleDocs, Wiki, AutoCad and SharePoint…

It’s here that the real creativity in engineers starts to shine. I bet you’ve created some amazing stuff suing a Wiki. Collaborative efforts via SharePoint and Google Drive can be downright inspiring. THere are some amazingly detailed diagrams on AutoCad. Problem, though? You’re no Tatsuo.

Who is Tatsuo? A Japanese artist who turns spreadsheets into masterpieces. It’s breathtaking and completely out-of-the-box art. That being said, most of us lack the talent and time to create something like this. Further, documenting networks isn’t done for the love of it – it’s done out of necessity.

If I had just a penny for every time I’ve heard, “But I can already do such and such task using a strange workaround”….I might not be rich but I could probably afford that Ferrari I’ve been eyeing for 20 years. I mean: I’ve heard of a guy using the recycling bin as his file storage system. You’ve probably heard about folks using their CD-ROM drives as coffee holders. It’s human nature to invent workarounds or strange habits and nerds aren’t immune. I once knew a programmer who absolutely wouldn’t use an IDE: he insisted on writing all of his code in notepad. Point? Just because you CAN do something doesn’t mean you SHOULD.

So, if your network is very small – I fully understand. Maybe a spreadsheet or a Wiki really is adequate. Those unsightly columns and rows may just be all that you really need. If you must keep up with the day-in and day-out changes to a 100+ object corporate network, however, automated network documentation is key to your success.

In Conclusion:

The philosophy that ‘monitoring is documentation’ brings in the automation but misses some key players such as diagrams, configuration items and other features. With the group of varied tools we went through above in Bill & Ted’s (not so) Awesome Adventure, you do get flexibility but you end up with a collection of products designed for something very different and no real automation to speak of.

Bottomline here? While we applaud your bootstrapping and creativity, get yourself a real network documentation system and leave Google Docs in the dust.

Jan Durnhofer
Jan Durnhofer
As CEO / Product and Engineering Manager, Jan joined Graphical Networks with the purpose of creating the most advanced DCIM and IT visualization company on the market.
March 24, 2017
Network Documentation: For Whom the Bell Tolls
February 15, 2017
Duplicating Objects with Cloud Network Documentation
February 15, 2017
Document Your Network to Increase Security

Leave a Reply

Your email address will not be published. Required fields are marked *

LiveZilla Live Chat Software