Hi Craig,

You bring up a very good question!  I think that many of us tend to forget to think about the cost of these docs and put them in perspective.

I remember a while back one of my managers, after reviewing one of my docs, asked me: "How many hours did you work on this?"  I don't remember but I must have said something like: 20 hours and then he asked "So would you pay $600 for this document?".  I was stunned because I realized that I would surely not pay $600 for the document I just created.  It wasn't that the document wasn't needed but it was of poor quality and incomplete.

This is not to say that creating documents is without value but it really gave me a kick in the rear-end and forced me to work on good habits and work ethic to develop high-quality documents, complete and with not defects.

So yes - we need to think of not only the cost (how much money did we spend to create the document) but also of the value (what is the financial impact of not having the document).

These days, there is a tendency to shun documents especially large ones - and for good reasons.  Many projects don't need a tone of documentation when the team is small, uses agile practices, may be a one time project with no need for future expansion.  Some teams need documents but they don't have the right talent or they simply use "the template" dictated by some process which was put in place years a go and nobody remembers why and whether the assumptions true back then still hold today.

In my experience, the decision of how much documentation (and if any) to create is not a one time decision.  The analyst and the management team must constantly re-evalute the state of the project and organization, needs of the business, future plans/goals and determine if more or less documentation may be needed.

For example, you're leading an agile team for a health care software vendor.  You use agile practices, you write the user stories on 3x5 cards, once  the iteration is over and the stories have been implemented you dump the cards.  Things work very well!  Product gets updated often and with great impact from the clients.  Everybody's happy!    Then the things talked about in this story (Just What The IT Industry Needs -- More Regulation) become true.  Aka  - the government begins to regulate how health-care software vendors deliver software and they mandate "proof" that you've followed a rigorous process and that you know what your software does.  In this case, you might consider creating and keeping more documentation.

I've worked on projects in an entrepreneurial environment where the key goal of the product was to "get it out there and show it to the investors".  Aka - speed to market was critical so any "non-essentials" were cut including documentation.  We were agile and did "just enough" to get the product out the door.  The project sponsor got exactly what they asked for.

On a different project I worked on we had to develop a new system was for a large Fortune 500 company, in a heavily regulated industry, for a very complex business domain, there was a need to be able to respond quickly to changes in business climate and new laws, and with the goal for the product to be a multi-generation system with a shelf-life of 10+ years.  Do you think we created more documentation then simple 3x5 cards?  You bet!

I just wanted to illustrate that knowing the cost of documentation is very important but as important is knowing the cost of not having the documentation.

- Adrian