Duplication in Infrastructure Documentation is a Good Result!

I keep hearing expressions such as single pane of glass, single source of truth, golden source, zero touch documentation and other similar expressions – often part of marketing campaigns to address the common problem of poor IT systems and infrastructure documentation. A common theme is that duplication of data is bad and unmanageable, so a trusted solution can only be delivered by an integrated, consolidated system with automated updating. Heard this before?

A project is formed, lots of money is spent and a set of extra data is delivered which is only used by a few and many just carry on as before - doing their best. Often the information needs or work processes were not understood in the first place, with the project journey focused on technical data and descoping tricky areas like physical, business, teams, grouping, timing and presentation aspects.

My volunteer work with the TIA TR-60 ICT life cycle management standard has been fascinating as I currently chair the committee tasked with delivering an infrastructure documentation standard called TIA-5077.1. Talking with other professionals in great detail about information needs has expanded our group awareness and made me understand why duplication is a good thing, very necessary and welcome – contrary to some prevailing opinions. Maybe its time to sit around a table and discuss common sense approaches rather than ignore "the dead elephant in the room". Lets start with the infrastructure information needed to simplify tasks, reduce risks, reduce workload, enabling team working and predictable project delivery. May take longer than an hour...

About 20 years ago when developing the first versions of the AssetGen system, I recognised that IT project and operational processes require information in different formats, levels of detail and presentation - to help communicate, inform and pass knowledge. Just a few formats you will find IT infrastructure components duplicated in are listed here:

• Documents covering policies, configurations, procurement, QA, testing, etc.
• Design documents covering systems and architectures (HLD, LLD)
• Lists of devices, configurations, project BOM and support details
• Diagrams showing locations and dependencies from physical, system and business perspectives
• Workflow processes covering projects, ITSM management, compliance and security
• Standardised procedures and controls covering implementation methods
• Monitoring systems showing capacity, status, security logs and performance

So you should expect a switch, server, application or system to be found in many places – as it is needed by different processes and inter-team communication. It becomes a problem if a switch only appears in an asset list, but not a network diagram, or the rack it is in, or a list of devices connected to it, or a list of services impacted by rebooting it. Duplication is good, but does need to be managed or no one trusts any information provided and manually reverse-engineers the information they need for a task – often by surveys, workshops and audits.

So how do you manage the necessary duplication?

Keep things as simple as possible and re-use data to help show different views of any component or system. You might find a spreadsheet a good start, but for scalability, flexibility and control you'll probably end up using a database. Not everyone is on the same page, so its a good idea to assess the current position and communicate where quick wins can be gained. Using the same names across information sets, assigning ownership, having an update period agreed are just a few basics to start with. There could be a documentation mountain for the company to climb if the starting point isn't even on the road to the top. It helps to be?prepared and ready for the journey to a better place, but even better to have a plan with the start, end and the milestones in between.

In the Visio corner my colleague Callum explains how he developed a method to look at any Visio diagram and then report cross references to other diagrams with the same component / application. A bit like a content checking except that while it is easy with word and excel, it isn't for diagrams. Where his method goes further is to insert hyperlinks to enable drill down/to from a shape directly to other documents and centering the diagram on the shape. So a server in a rack can be quickly referenced in HLDs, LLDs and application diagrams as well as backup and recovery plans. Assessing the level of duplication is quick and it also shows differences and inconsistencies which can be easily fixed. When servers don't appear in racks or VM environments, but are critical to an application - something is wrong. If only the servers had been duplicated in other documents so we at least knew where they were... ? ?

Dave's Pet Peeves

In this newsletter we have covered many Visio related issues, as a lot of our work delivers diagrams than show complex dependencies. My pet peeve this time is how a well established product like Visio is underused simply because of a lack of awareness and understanding. Every day we demonstrate good methods and practices of documenting IT systems, often using existing Visio automation features. So many times we have heard "I've been using Visio for over 10 years, when was that feature added that enables Excel to help create diagrams!". Over 16 years ago is the answer.

I've seen IT equipment manufacturers create free Visio stencils and design tools that aid design and operational management, but fail to pass on how to use the stencils. Many years ago I presented Visio automation to a 50 strong technical support team of a major manufacturer of cabling infrastructure components. I used their free stencils as part of the presentation. Out of 50 only 8 had ever used the free stencils and only 2 used Visio regularly. The reason was that the company had never shown anyone how to use Visio for drawings (so they used PowerPoint), never mind how to use their stencils. Expecting people to pick up MS office tools without training or standardising formats doesn't help their productivity and confidence.

I wonder how much expensive IT engineering time is wasted because personal or individual productivity toolsets are purchased without training or support. Just because they've used 5% of the capability over 15 years doesn't mean they are proficient. Have a look at our website where we have YouTube videos, webinars, free Visio add-ons, etc. that help save time diagramming with Visio. Maybe training on a toolset that you already have makes sense? It will be me that answers the enquiry... some of my knowledge will give immediate payback.

Visio Corner - Automated Hyperlinking

Having multiple views of the same components is very useful however there is a practical issue that can arise, as the number of different views can start to balloon with the number of documents that have to be maintained. If you updated a component in your rack diagram, the diagrams for networks / vlans / data flows /service maps etc.. that have the same component also need to be updated. You can see the problem here, how do I know which diagrams need to be updated? You would have to manually go through every possible diagram to check if the same component exists. This is also presuming that you are able to identify the same component in another type of diagram, as what may be called “ServerWin001“ in your rack diagram may be called “Primary Application Server” in your service map and even use a different symbol.

Another method I will talk about is Hyperlinking to Visio shapes. I talked about this method in the last Visio corner on November 10th where we can hyperlink a component to every diagram it appears in. Of course, doing this manually would be a monumental effort for most IT Infrastructures, which is why we developed an internal Visio tool called the AssetGen Diagram Hyperlinker to programmatically search and hyperlink entire diagrams together. This tool uses the independent IDs that the AssetGen Connect and SysMap database assigns to components to search multiple Visio diagrams. When it finds a match, it will create a hyperlink that when clicked will take you to the page the matched shape is on, center and zoom in on that shape. In a few seconds you can create drill down links from devices to multiple sets of diagrams.

It is important to initially assess the possible matches (and mismatches) between diagrams, so we included an option to create a report in csv spreadsheet format that lists all the hyperlinks and documents that would be created. The tool also lists where selected components do not match to show gaps and inconsistencies. Below is an example report mapping every device in the rack diagram shown before to other diagrams and the pages involved. A quick way to assess duplication and inconsistency in multiple diagrams at once.

Since the tool uses an AssetGen database unique ID, the AssetGen Diagram Hyperlinker can cope with different names for devices and applications. Using Excel/Visio data linking isn't really practical for automation techniques to work if there are more than a few diagrams. Database driven diagramming simplifies automation of checking, linking and updating of the many schematics that exist in enterprises.

In hindsight we found the mapping assessment csv. report so useful that we pasted it into a master diagram to aid future updates. It gives the location, filename and page that anyone viewing the diagram can see and refresh. If you would like to know more about AssetGen Diagram Linker and our other internal Visio developments please contact us via the web site.

Upcoming Events - December

December 14th – Free Webinar, Planning and Managing Cabling Infrastructure - Part 4 Managing capacity Details & Registration 13:00 UK 08:00 US EDT

The final webinar of our series on Planning and Managing Cabling Infrastructure looks at the management reporting and life cycle issues that cover existing and new cabling infrastructure. Understanding and reporting capacity, decommissioning, upgrading, billing, evolving control processes and changes in contractors. The management issues that need to be addressed to keep costs under control and meet business connectivity needs.

I hope you enjoyed this edition of this newsletter, make sure you subscribe by clicking the button at the top of the page to keep updated on future articles and events.

Square Mile Systems | Free Visio Utilities