I constantly struggle with writing documentation and also communicating concepts to many IT folks in writing.
This is one of the reasons that has driven me to producing videos and capture sessions over the past couple years (I can say far more, more accurately with combined speech and visuals than attempt to accurately convey in writing).
My work as a moderator of the Hyper-V TechNet forum also speaks to this. I spend a great deal of time describing concepts in forum posts – that end up being incredibly long. Each time I write it a bit differently, still trying to convey a concept.
The reason for this post? Accuracy. Accurate conveyance of information.
This all started with a recent trip to the doctor. 20 minutes of discussing things with my doctor was summarized into a single paragraph of Latin. The use of the common language of Latin to describe symptoms, and convey that description from doctor to doctor.
I am not proposing that Latin be revived in IT. However, to use commonly understood grammatical structure to describe concepts, or installations, or topology, or systems architecture.
This gets even more complex as we move into the virtual workload world. Where we describe physical characteristics in a non-physical way.
A virtual appliance for example. In its most common representation today, this is a virtual machine – installed within that virtual machine is an operating system and some application. The application and OS have dependencies – DNS, networking, Active Directory authentication for example. The machine has dependencies – two virtual NICs, one public facing, one that faces a private subnet that connects to the database server. Oh, and now we have an external entity of a database server. Where does it all end – I don’t know of a single workload that exists in an enterprise as a single entity.
The struggle is: How do we describe this in a universal way so that no matter where you take that appliance the environment knows what to do with it? How to configure it. How to connect it. Where to connect it.
This is the role of a Standards Body – in this case the DMTF is attempting to build this common term framework. But this is a framework, it is not universal terms – it is simply items or entities. So at least we begin with common items – however describing them in different languages by vendor.
Now, how do I take that DMTF developed structure and tern it into words. One set of words that can be used in association with a NIC to describe its network connection and then the attachment and VPN attributes.
Or, throw that idea out the window and focus on describing the interactions between the workloads only. Don’t describe the physical topology in any way – simply describe the dependencies between workloads or appliance entities.
Most IT folks would never see this description language – but integrators would find it useful, documentation folks would find it useful, and even developers would find it useful.