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.

I use Evernote to make that information available. I have been using it for work and play for about a year, and it is has become a tool I just can’t live without. Evernote is available on the Web, Desktop, iPhone and other mobile devices and systems. This is how I have been using Evernote.

Project Information

First of all, to get information about the project I am working on. Where I work at the moment, there are many projects, which I may not be continually assigned to. This makes it difficult to keep in mind all of the things you need to know. Server address, UAT connection details, information about the project, recent work carried out. In essence anything that I deem interesting or important about a project gets thrown in to Evernote.

Evernote makes it easier to get back up to speed on projects rather than having to review the somewhat dry read which is the technical documentation.

Bug Fixes

If I have found a fix to an error I get on a project it is good to record this in Evernote, as it makes the fix available to other projects. Granted this is not as useful for very specific bugs but when you have issues with the Microsoft Enterprise Library, that information is going to be useful again.

To Do Lists

If I am working on a large job. I record all of the elements of that task as a Note. I can then check of each item as I get it done and as new things crop up and I can extend the to do list. So now I don’t forget where I am up to or what I have left to do.

Have a look at Evernote and let me know how you end up using it.