Why should we document?

As a reaction to large overwhelming (enterprise) architecture frameworks such as TOGAF and RUP the agile manifesto stated a number of things in an ambition to produce better software in a more efficient way. One of the things that were stated was

  • Working software over comprehensive documention

As many have said before me this does not mean we should omit documentation, but I think many developers read this statements as

  • Working software over comprehensive documention

Many developers want to write code and so do I. It is fun to write and to run the code and see it working. We don’t have the time to write that documentation since we are on our way to write the next masterpiece of code or we think we will document once we are done. Well, probably the most common reason is lack of time in order to be able to finish the system or product. But, aren’t we just fooling ourself in the long run. As most other human beings I tend to forget things very fast, even the code I have written myself.

People are leaving the company from time to time

People are leaving the company and bring the local information

People tend to quit their job after a time. Some sooner than other and in the IT industry people tend to change more often than in other industries. When a person leaves her job a lot of knowledge is walking out of the door and it takes time to recover from that loss. But, even we who stays we tend to forget and loose knowledge and information after a while. It is a human defect (or a blessing) to forget things that has happened or being said. In the IT industry we are kind of sloppy regarding taking notes and document our work properly compared to more mature professions such as Architecture, Physics and Legal.

Yes, it is true that might loose time to document since the design will change. But, I strongly agree with Andy Hunt in his book “Pragmatic Programmer” when he states “Perhaps the most important is to write/visualize”. It is the same phenomena when we explain a problem to colleague (or a rubber duck). During the explanation we find the solution in ourself. Forcing us to document we get better and faster of writing and drawing, but we also find a lot of bugs or design errors during the writing/drawing.

Old documentation
“The worst thing I know is outdated documentation. It is better with no documentation in those cases”

This is a rather common stated opinion. I don’t agree. I would say “it is better with outdated documentation, than no documentation”. For me all kind of documentation of code, design and architecture gives you an idea what was the purpose of the design and code when the information was discussed and formulated. If you use the SCM for the documentation you are able to get the code how it looked like when the documentation was written and you are then able to see the evolution of the software being developed.