Having worked the last 10 years as an IT consultant for a leading systems integrator, I have written my fair share of documentation. From design documents, migration plans, test plans, operational guides and health checks, I’ve done it all. But nothing annoys me more than having to write as built documentation.
What’s the problem with writing as built documentation?
As built documents require a lot of detailed system information, which often takes a significant amount of time and effort to retrieve. The information then normally requires you to transpose it from one format to another, again a laborious and time wasting exercise. In rare instances you may find a tool that can do this for you, however, it is never free, and it will never be able to perform this task across all of your systems. Sure, there’s always some basic tool available which can export into CSV, however the pain lies in transposing the information into a document format which is legible and presentable to a client. Excel spreadsheets are never acceptable to clients paying top dollar for your services.
Isn’t an as built document simply an update to the detailed level design?NO!
Isn’t an as built document a procedural guide of how to install and configure the system?NO!
The sole purpose of an as built document is to report on the current state of a system, to provide detailed information on a system’s characteristics, such as hardware specifications, serial numbers, MAC & WWN addresses, and software versions, patch levels, settings and resources. This information is unknown during the design phase, so it should certainly not reside in a design document.
Is there an easy way to generate as built documentation?Yes, there is now!
Producing detailed as built documentation is difficult and the quality of what I and many others have produced in the past is simply not satisfactory. Recently I thought, there simply had to be a better way to do this, and there is with PowerShell.
I knew PowerShell was capable of retrieving and storing lots of information, many IT vendors had now begun to provide their own PowerShell modules and snap-ins (yuk!) which made it easier to extract information from their systems. However what I didn’t quite know was how to output this information into a format which was clear, consistent and easy to read. I was aware of
ConvertTo-HTMLcommands, however these methods would still require some advanced level of coding, to produce what I was looking for, and I simply wasn’t there yet. I needed a simpler approach!
Want to know more?
Be sure to attend my VMworld US 2018 session VIN3327BU – Documenting Your Virtual Infrastructure with PowerShell and PowerCLI on Wednesday August 29, 2018 from 2:00-3:00pm to learn more about how I overcame these challenges, and the tools and methods I used, to produce as built reports which are are simple to run, are both modular and granular by design and which support multiple document formats to provide consistent and customizable outputs time and time again.
I look forward to seeing you at my session!
For those unable to attend my session, never fear, I will be updating this post following my VMworld session with all the important information you require.
Please stay tuned!