Documentation

When it comes to documentation I am firm believer in the quote of Antoine de Saint-Exupery:

“A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.”

As I see it there are a few main purposes of producing documentation:

To convey understanding - This shows my quite liberal view of documentation since I consider drawings on a white board or a napkin to be documentation. But I also consider this to be one of the most important purposes of documenting things. From a designer’s viewpoint these “documents” are vital in going from an inner vision to an operational image that can be shared by others. Common examples of documentation conveying understanding in large organisations are presentations given at various meetings. These documents can be saved for posterity, but the ability to convey understanding is much smaller for those who weren’t there. On the other hand are written documents one of the most efficient means through history to build on knowledge of others which you never had the opportunity to meet.

To formalise agreements – If there is a business agreement between two organisations it is almost inevitable not to have a more formal document detailing the technical content of the agreement, the specification. many organisations, including my own, also use documents to formalise the agreement between internal teams. Your mileage may vary how efficient this is in various organisation.

To preserve information – The human memory is not infallible. Documentation is a great support to minimise the decay that is inevitable when only relying on the human mind. Software is also about maintenance and any body who has been given the responsibility to update legacy code that is undocumented know how difficult it is (this scenario includes the purpose of understanding as well)

I don’t buy “the code is the documentation” at all. The code by itself does not fulfil any of the purposes above.

I have recently worked in a project which solely relied on Trac to capture all information relevant to the project (except finances). I am positively surprised how much you can achieve with so little formal documentation in combination with having everything in the same place available for everybody in the project. I will try to do a more formal evaluation according to the purposes above when the project is near it’s end.