Monday 23 December 2013

The Devils in the Documentation....not quite but its a start!

So being a software engineer I find myself getting frustrated with the lack of emphasis put on maintaining light weight documentation. Now don’t get me wrong heavy weight documents outlining every single intricate detail of a piece of software is not only a waste of time to the person writing it but also a waste of time for the person reading it. When you start working on a piece of software, particularly something new to you, you need a few things to get you going and point you in the right direction. 

One is the existing code base, ideally nicely written and self documenting with meaningful class names, method names etc and a little magic which isn't avoidable. Another must if you are going to be working on a meaningful/sizeable feature is a basic overview of the system, its interactions basic concepts. Not only do you get a feel for how things currently work, you get a feel for how they fit together, how you can add value, how they may interact with other systems. You get a snapshot of naming conventions and vocabulary which hopefully should be mimicked in the code base. There is a useful tool call code-words for extracting out word clouds used within a code base, run it against a code base you are working on and see what you find, it may be interesting. Combine these things together and getting up and running on a new project or new feature is much easier in my opinion. I don’t even have a preferred type of document of diagram, sequence diagrams, UML heavy weights, simple process flow diagrams, these all can bring value and are better than nothing. Obviously the caveat is that you need to ensure you include the time needed to update these bits of documents and diagrams as you add value and change systems over time otherwise they get out of date and tell a different story than what is really happening. Diagrams in my opinion are much easier to update, easier to maintain and much more fun and enjoyable to work with. They don't always show you the fine grain details which you need, in my opinion these are found in the code base and possibly in more focused diagrams looking at particular interactions or solutions.

I think the real point here is that the documentation of a system needs to be treated with respect just as the code, the tests, the infrastructure and the business itself should be. The devil is always in the detail and the details are going to be in the code base or peoples head, the documentation will give you means to pin point where to find the details and hopefully not make assumptions which turn out to be unfounded. 


I feel that this relates to all software engineering I have done, open source, personal and at an enterprise level. This post is purely a complete rant after hitting several issues to do with the lack of knowledge or information when working on projects professional and in my spare time....rant over! Basically stop being lazy and give me a simple digram!!


James Morgan