This post is the first in a series of articles tackling the topic of creating and maintaining proper network documentation. Each article will include a file which can be downloaded and used as a template for creating the document covered. Below you will find a few generic documentation best practices which apply to all documents covered along with a list of links to each of the articles and their respective templates.
I will be updating the list of links as each piece is published
All of my examples are created using Microsoft Visio 2010 Premium. Few would argue against the notion that Visio is the most popular tool for the job; and its ubiquity makes it easy to share editable content and find stencil (icon) libraries from vendors.
Versioning is a very important part of the documentation process. It keeps track of changes to the documents, and also makes it obvious to a viewer when they have an outdated copy. Here are some guidelines I like to follow when working on documents and moving through versions.
X = Major version number. vX.0.0 is a version which can be distributed to all teams in the company as an approved and ready document.
Y = Minor version number. This is to be used to increment draft releases of the document destined for limited release to technical teams for approval/discussion purposes only. Any Y version other than 0 should not be sent out as a final release that is ready for distribution and implementation.
Z = Internal versions. This is to be used to track changes to the document internally. Any Z version other than 0 should never be sent to another team at all.
One of the first rules I teach junior network engineers is to “document, then implement”. Many mistakes and bad design decisions can be avoided if changes to a network are documented before they are implemented. It is much easier to catch mistakes and bad designs visually on a diagram or spreadsheet than it is to read them off of a CLI. Aside from that, how often do we remember to update the docs after we make the changes? I often times forget, which is why I recommend the practice of “document, then implement”.
When saving and/or sharing your diagrams with colleagues (especially when sharing with members of a different team), make sure to save your document to a PDF format and distribute the PDF (not the VSD). Many IT professionals do not have a copy of Visio and cannot view a .VSD file. This practice also keeps other teams from modifying the drawing with their own content (often non-network related content) and distributing a competing version of the network diagram.
Properly exporting to a PDF can be tricky. I’ve had bad experiences with PDF printer emulators where they distort all the colors and do strange things with transparency and gradients. I personally use the “Save to PDF” function which is a feature of the “Premium” version of Visio. If the premium version is out of the question for you, you can use JPEGs in the standard version, but keep in mind that you can’t save multiple pages (which translate to tabs in Visio) to a single JPEG.
Other Useful References
|Favorite Cisco Generic Icon Library||http://www.cisco.com/web/about/ac50/ac47/PPT_vss.zip|
|Cisco Generic Network Topology Icon Homepage||www.cisco.com/web/about/ac50/ac47/2.html|
|Creating Custom Line Patterns in Visio||http://viziblr.com/news/2011/10/4/visio-creating-double-lined-shapes.html|
|Creating Layers in Visio||http://www.virtues.it/2012/05/visio-layers-pt1/|