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.
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?
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
There is a question that often returns: How do we know which analysis techniques we need to apply? There are of course several considerations to be made.
You can for example consider the nature of the system or the composition of the team. One good place to start is to take a look at the stakeholders of your analysis. Whom are you making it for?
Despite agile and lean being more popular than ever, 200 page analysis documents are still very much a reality. There are many reasons why you shouldn’t write this type of documentation but if I would have to choose one major reason it is that nobody actually likes to read these documents. Here are some other good reasons not to.
It is hard for anyone to remain consistent throughout a long plain text. Inconsistencies already start creeping in while you’re working on the first version. Then updates are made by you or even more risky, by other people. (If you don’t believe me, just take a look at all the inconsistencies in the Harry Potter series.)