I Like Documentation!

OK that probably does not leave me looking anything other than geeky, but never-the-less: I do.

Why do I like it? Or should the question be why do you not? It can be an extremely efficient way of obtaining large amounts of information about a project in very little time. A visual representation of a system gives a better understanding of a project overall, than a long-winded contract or several hours of perusing code can ever do.

Well written, considered and thought out project documentation can be a huge time and money saver. Sounds good doesn’t it. So why do developers hate documentation? Why don’t we ever find the time to keep it up to date?

Well, from what I have seen project documentation doesn’t get updated because there is generally no one in the team who actually owns it. It is seen as a pain and a chore; because lets face it, most people like to jump in and hack the code and why would we want to sit and write about what we have just done; we have done it already! You should be able to read the code, blah, blah, blah. Excuses. Unfortunately, our colleagues don’t fully understand that their rushed implementations or their bag of buzz words, latest technologies, multiple levels of indirection, inversion and misunderstood pattern implementations, are not easy to understand. And frankly, in three months time they won’t understand it either. Rant over.

And just having documentation isn’t enough. I have seen documentation associated with development projects which is out of date, poorly written and of very little value to anyone. Occasionally, developers are required to update documentation that is actually intended as contractual business documentation; again unhelpful.

What Constitues Good Documentation?

OK. So what constitutes a good set of documentation in a project. One acronym – UML. A picture paints a thousand words and all that. Now don’t get me wrong, I don’t think you should document every inch of code in a project. But even a document giving a generalised overview of the project, its architecture, architectural intent and diagrams which show visually this information; is priceless.

Observer Pattern

Time to put my money where my mouth is. This is what I think you should seriously consider having as a basic documentation set.

• Architecture. A UML diagram showing the constituent parts of the architecture, a description of the system and its intended purpose.
• System. You should document and diagram, with class diagrams, the major sections of the system. Again with a description of intent and purpose.
• Document complex interactions. In larger systems there are at least one portion of the system that requires a little more thought because of that clever implementation. Make sure it is again documented. A sequence diagram showing the interaction between classes and again, description of intent and purpose.

With this all developers will know how the system is architected, what it was supposed to be doing and how it is achieving it. This means that when they come to fix a bug or modify the system because of change requests that they understand what needs to be changed and how that effects the rest of the system. And of course they would update the documentation so that everyone else knows as well.