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.

Inconsistencies

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.)

Completeness

A text does not force you to be complete. You are free to write without constraints, without ever being triggered that you might be forgetting something.

Overview

No matter how many chapters and levels you add to a document, a lengthy document can not give you a clear overview.

Communication

To my horror these documents aren’t just used for analysis purposes. Some people also use them as a replacement for communication.

Just read the document. Everything you need to know is in there.

But communication and collaboration are crucial. Instead of passing documents, you should be involving team members from the start, allowing them to build business knowledge. You should be collaborating to come a great solution together.

And there are many more reasons not to go down this path:

• The difficulty to keep such a document up-to-date
• Such long texts do not lend themselves to discovering conflicting and missing requirements
• Creating a design in a textual document is simply not possible

An alternative

I wouldn’t be writing this post if I didn’t believe in an alternative. Using analysis techniques such as information modeling, use cases and state diagrams can help you.

Let’s take for example information modeling.

If you use an information model, this means that all your information is described in one place. In any other specification you make, you don’t need to explain the concepts or the rules that apply to them. There is no risk of being inconsistent about information, as it is only described once.

An information model makes you think about different aspects of information. First you need to specify the concepts and describe them. Then you need to think about the relationships between them and their multiplicities. You describe the properties of the concepts. The technique reminds you of what you need to specify and by doing so it helps you to be more complete.

Last but not least, information modeling is a great example of a technique that you use when you’re all standing around a whiteboard. It is something you will want on your project wall, so that everybody knows it.

There is a downside

Using different analysis techniques also has a downside: you miss cohesion, there is no glue in between the diagrams and techniques. The 200 page document can neatly knit everything together with text. But really, who needs text when you have communication?

Like this Blog?

Then you’re in for a treat! Visit Sarah Denayer’s personal blog, which offers many more hours of excellent reading material!