Documentation: Yes, I know it's a pain, but it's needed.
Written by Kip Ng, Principal Microsoft Premier Field Engineer
As a Microsoft Premier Field Engineer (PFE), one of our primarily roles is to perform risk assessments on client IT environments. Of course, we always have very well defined scope as in which Microsoft product that we are reviewing. One of the major issues that always come up from these reviews is the lack of updated documentation or, sometimes, just purely lack of documentation. This prompted me to write a short post on this specific topic.
Documentation is an essential element in any IT project. Documents like technical specs or requirements documents, design documents, build documents, and disaster recovery documents (to name a few) are very important. Ideally, these should be the first things that come up before any deployment. Unfortunately, in most of the IT projects that I have seen, including some of those that I was involved in, documentation seems to be the last thing that happens. Sound familiar? If you participated in IT projects before, I’m quite sure you’ve been in one where people document steps or the build document after-the-fact. Some would even create diagrams or write their architecture and design document after everything is complete. And there are some who initially thought they will have the time to document after the implementation but moved on to the next project right after, resulting in a project with little or no documentation.
As a Microsoft Certified Architect in Messaging, I also do design and architecture reviews and I can tell you there are countless times when I asked for the full requirements docs, technical specs, design and architecture documents. In one case, I was presented with just a diagram and a person who said “If you have any questions, you can ask me.” Or sometimes I’m presented with documents that are nothing more than downloaded templates, some even referencing other companies or Microsoft’s sample companies (Fabrikam or Contoso). There were also many times where I’m presented with documents where the design is totally different than what is being deployed and I’m told that the design changed, they improvised and nobody cares to update the documents. What’s the point of those documents then?
What I’m trying to say here is this: YES, I know documentation is a pain and YES, it takes time and YES, nobody likes to do it and I don’t too. However, if I ran the IT shop, I would force myself to do it even though I dislike it. Why? Because documentation is important to the health of ongoing IT operations, to future projects, to your people (new and old), to recovery, to make things repeatable, to understand the history, to understand the limitations, to have the appropriate steps to recreate the environment, and I can continue this list till the end of days. Believe me, it’s worth investing your time and money in it. Not to mention, it will make my life easier as a reviewer (if I or any auditor or reviewer happen to come into your company to review your environment).