Friday, February 4, 2011

Documentation – Format and How Much?



I have been trying to establish a documentation approach for my team and there seems to be only varying well entrenched views, and no consensus on this. There are two sets of opposing viewpoint camps that I see. Agile Vs. Formal and Everything Vs. Minimal.

Format

Agile Documentation: When you document keep it informal. This makes documentation easier to create but harder to use as there is more searching in the documentation for the information you need. There is also more possibility that something will be missed in the documentation
VS.
Formal Documentation: Use a ridged template for documentation. It takes longer to create the document and there are commonly sections that go unused. In addition some section will be filled out with information that is being mandated but provides very little value for the application it’s being used for. The end result though is as the template is used over time it becomes easier to find information in all documentation.

How Much

Everything Documented: This is supported by the belief that most of what we do in IT is a reputable process and that this documenting will be reused many times there for demonstrating the ROI.
Example of good ROI: Deploying PC’s even in a small company this is a repetitive task that happens at least many times a year if not many times a day. There is no doubt that this displays the ROI for creating the documentation.
VS.
Minimal Documentation: This is supported by the belief that in IT most of what we do is so unique that the documentation provides little ROI and is largely created as a formality and will never be looked at again.
Example of good ROI: Installing a new centralized business application on a server. Most companies only have one install of these installs in their entire system. If they are done correctly and with a proper selection process this install should have a life span of at least 5 years. Yes there will be upgrades but an upgrade process and an install process are extremely different. There is very little ROI in documenting this process.

Prevailing Logic

I think in leadership we tend to lean towards the Everything & Formal approach. Excusing the chorus of our teams pressing for the Minimal & Agile under the tenant “IT people just hate to document”. I do think that's true, but I also believe as much as we trust our team to tell us what a server can and can’t do we have to extend some trust to them as to when there is value to document and when there is not.
We should also not overlook that we work with people, and we can “force” them to do things but just like the speed limit there may be a rule but it will be bent as much as possible, and we can’t be everywhere at once to police it. The more they agree with the rule as it
’s presented the more they will follow it. Why do most parents dive the limit in a school zone, when children are present?

So what am I going to do

This is yet
another topic where I wish there was a right and a wrong answer. I don’t know that there is and I don’t know that you can set one mandate for all teams and all situations. I have started on a path for my team to gather all documentation with a common search index and folder structure. Utilizing one primary application for making our documents but allowing flexibility to use other applications with a link to our primary where needed. I interpret that as a primarily agile method with a leaning towards documenting everything. Is this the “right” answer, I don’t know but it’s where I a
m starting.

As always I look forward to your feedback