We all know that one of the premises of the agile manifesto is to value Working Software over Comprehensive Documentation. This is a wonderful idea and it takes a tremendous burden off of project implementations. I have seen as many projects fail because of the maintenance weight of the project documentations as I have for any reason.

But this goal as important as it is may not always be practical. Sometimes the client will simply insist on tedious documentation despite the arguments against it. This may be to calm a nervous client. This may be to satisfy an audit / compliance requirement. This may be a non-too subtle attempt at sabotaging the project. Ok, it is probably not an all out attempt to sabotage the project, but it will probably feel that way.

So what can we do to keep to the spirit of the Agile Manifesto but still meet the needs of the client wanting the documentation?

This is a good question that I have been puzzling over lately! I hope to explore some possible answers more fully here.

A common theme that my solutions are likely to follow is the same theme that I often follow with simplifying complex business logic.

Make it table driven!

My thought is that the sought after documentation could be a report or reports out of a metadata repository. Reports are much easier to maintain than hand written documentation.

Here are a few additional advantages that we can explore over time:

• Reports will take advantage of the fact that different people have different needs and different format requirements
• Reports and the supporting metadata are more easily validated and the validation can be automated.
• If the application itself uses this metadata than there never has to be a question as to whether or not the metadata is up to date. It is up to date or the application would not work.
• In many cases we should be able to automatically gather most of the Meta data that we need using reflection, system tables, etc.

I think that this will lower the total cost of ownership for the documentation and may provide something useful beyond having a pretty document to look at.

What are your thoughts?