More on the Nurnberg funnel

Hans Wegener e-mailed me with some interesting footnotes on the Nurnberg funnel.  He pointed out that it is not enough to consider risk alone when deciding what documentation to write, we also need to consider cost. He is right of course, the question is: how do we establish the cost of writing documentation?

If we are going to talk about cost we should also talk about benefit.  As well as asking how much does documentation cost we need to ask: what are the benefits from the documentation?

In my experience written system documentation tends to go one of two ways.  Either the project considers it absolutely essential.  In this case documentation tends to get written even if it means sacrificing something else - like actual working code.

Alternatively projects start with lofty ambitions to product documentation but this tends to be pushed to the end of the project and sacrificed when deadlines approach.  In this aspect documentation is similar to testing: everyone agrees it is a good thing and we should do more off it but among the first sacrifices when problems set in.

In both cases the benefit of documentation is not understood.  What we need is a better way of judging the benefit of documentation.  If we could do that then we could determine how much to spend on it, whether to write lots of it or whether to sacrifice it.

My problem is that I have not data on this.  For all my comments and opinions it is all just speculation based on personal observation.  Trouble is this is the case for most other people too.  We all guess at how much system documentation to write, how much time to spend on it, and how many people to employ doing it.