I was talking to a friend not so long ago about documentation. My argument is that writing external documents in order to define the behaviour and interactions of software is (or should be) covered by the business/stakeholders in their requirements or with the acceptance tests that have been defined for the application. There is of course a need to document the technical details, such as why you did something the way you did, and I feel this is best covered from self describing, well written, Unit Tests.
When I suggested this, I received a response similar to "the phase 'Unit tests and code will document behaviour' does not cut it with me...the key is to write small and focused documents". The problem with this approach is the documents are external to the developers environment and having to update x number of documents each time you make a change becomes a chore and arguably not necessary.
If we think about why we are test driving our development in the first place, it is to drive the architectural design decisions out into the code. These tests are therefore the best place to understand why the application was written in the way it was.
Using unit tests as the main documentation for the project also has the added advantage of evolving naturally with the application; the so called "living documentation". When you want to change the application or fix a defect, we always start with modifying (or creating) the tests first, then implement the code. This means our documentation is automatically kept up-to-date as we go... without having to search around a document portal and updating a number of Word or Visio documents.
I have seen many external documents getting created and people just not maintaining them. This completely destroys any value in even having written documents in the first place. The question to ask is why are these documents not being maintained? Perhaps it is because people forget, or perhaps they have pressure to get the application written? In this scenario we have simply wasted valuable project time.
Another well known fact, is that the majority of developers don't read written documentation for a system, because they naturally prefer to work with code. If they don't read it, then why have we just spent the time and money writing them? When trying to understand how a particular class works, it's easier and more productive (for me anyway) to look into the code and see for myself. I don't have to worry whether the document I am reading is up-to-date or comprehensive enough.
I can't execute my Word document or Visio diagram in order to prove the application functions as the document describes, in other words I can't verify the documentation is accurate. With well written unit tests we can.
The argument for having both written documentation that is already described in the unit tests go against the recommendation for single source information that is described in more detail here: http://www.agilemodeling.com/essays/singleSourceInformation.htm
Despite my arguments against external documentation, I still see the value in creating high level "overview" documents, just to give someone a brief understanding of what the application is and how it fits together, without needing to get down into the code.
I would be keen to hear others views on this subject, perhaps I have missed some real value in writing and maintaining these documents?