A few weeks ago I participated in a hackathon organised by AE. We began friday morning and by saturday night we had to present our idea and demo our product. Our team consisted of four awesome technical wizards: @thomaux, @glenndejaeger, @piether and Alex Wauters. As you might guess, I was the analyst.
The beer coaster analysis
It’s Monday morning and the daily scrum just took place. An analyst got the task to dig into a problem. He eagerly starts working on it at his desk, digging deep into the issue trying to make it crystal clear. Doing everything he can; creating diagrams, modeling, drawing, … Putting in time and effort. The analyst goes to the developer’s desk to discuss the fruits of his labor. While going through the entire stack of documents, he figures out that all he needed were some quick sketches on a the back of beer coaster. So where did he go wrong?
Integration : Dr. Jekyll and Mr. Hyde
In the last 5 years of my career as an enterprise architect, whenever the word "integration" came up, discussions started about the choice of an ESB (Enterprise Service Bus), SOA (Service Oriented Architecture), FTP or web services, SOAP or REST, XML or JSON, etc.
In short, when involved in discussions about "integration", one most likely finds himself drowning in a multitude of technical acronyms and technological standards.
I compare the technological side of integration to the "Dr. Jekyll" personality : it is the side well-known to everyone, stable, under control and increasingly complying to uniform standards.
Why is your documentation getting out of date?
I have frequently started working on products where there was little up-to-date documentation. You usually only notice it as you go. You might find that one part of the analysis does not describe the latest changes. As you find more and more inconsistencies, you will not be able to trust any of the documentation, even though some of it might still be ok. So why does this happen?
How does documentation become out of date and what can be done to prevent it?
The Product vs Project dimension
Why should you be making this distinction?
If you are not making it, you probably recognize some of these issues:
- you are redescribing your product over and over again for every new project
- there is no documentation of your product as a whole, in stead pieces are described depending on what was relevant for the project
- It is hard to find existing documentation as it is organized per project in stead of per product
