As the date of my R&S Lab approaches, looking at practice lab diagrams, specifications and instructions left me thinking about documentation. I have always been of the opinion that documentation should be effective but minimal, but this has been at odds with the philosophies of documentation I have come up against professionally over the years.
This stems from a perhaps unjustified belief that someone who is going to look at my documentation in a professional capacity will know what they are doing. I have always thought that when presented with a clear, detailed network diagram, showing interfaces, circuit IDs, IP addresses and VLAN information and access to the archive of device configurations, the experienced engineer should be able to formulate a reasonable knowledge of the network in short order. Of course, all networks will have their oddities, which may need some more detailed exposition. And one of the most common things I have been asked to explain over the years is why someone who had long-since retired did something in a particular way, especially if that configuration was entirely reasonable at the time but now, ten years down the track, it may seem anachronistic.
But I maintain that effective documentation does not have to be, to use the classic cliché, War and Peace.
However, I have come up against a culture where my philosophy of documentation, which may be characterized as “writing for the competent” has met resistance. I think the assumption by the War and Peace school of documentation has been that network issues or implementations need not be attended to by networking professionals; that with a sufficient level of detail, the network may be rebuilt after the nuclear holocaust by the last surviving mutant janitor.
Which of course misses the point that when all you are doing is cribbing from a detailed set of instructions (which in my experience reached the absurdity of actually documenting each command entered to perform any given task), any deviation or anomaly requires a level of experience to resolve which obviates the need for the level of detail in the documentation.
There needs to be a happy medium in the network documentation. You can’t go too far in the minimalist direction, or the some of the finer detail may get lost, but too much documentation quickly becomes redundant. And if the level of documentation required is too onerous, then busy network engineers will not have the time to keep it current, especially if the network is even slightly dynamic. It is amazing how much useful information you can fit easily on a good diagram using good tools, especially if the hard copies desired by the documentation nazis can be printed in A3 or larger.
To make a further literary allusion, all the mariner asks is a tall ship and a star to steer her by. All I ask is a good diagram detailing the L2 and L3 information, a configuration archive and a good dose of experience.
Of course, as someone who worked on four generations of the same network over fifteen years, and could tell you the IP addresses of every switch and give you the reason why that particular addressing scheme was used in that building in 1998, maybe I am a little myopic here. Maybe my assumptions about competence and experience are old hat in the modern world where the specialist skills are being devalued and we really will need the gardener to be able to configure OSPF from your doco in a radiation-blasted hellscape. Feel free to comment.
About Matthew Mengel
