Agile Documentation – a Reality Check

Working software over comprehensive documentation.

That's one of the value pairs a lot of people see (in the sense of really recognizing it) when they think about agile software development.

I don't want to re-iterate the simple fact that the manifesto just talks about valuing software over documentation and not instead. I also don't want to stress the old "While there is value in documentation we value working software more".
I don't even want to point out that the manifesto doesn't speak about all documentation, but only about comprehensive documentation.

Nowadays – where almost every software development effort is said to be "agile" – so many more questions arise.

"The code is the documentation" is sometimes true. Not so much if – for example – corporate standards enforce a development style that is far from SOLID. (You have heard about “corporate agile”, haven't you?)

"The tests are the documentation" is also sometimes true – but what part of the system do they describe?

Where is the business side?

To me, the currently worst idea in this context is the notion that user stories alone can describe the whole system. While there are many good approaches that contradict this notion (like user story mapping, impact mapping, product discovery etc.) there still is a lot of this mindset present in the wild. Especially when people use Jira and think that merely putting user stories in Jira tickets will leave the party who actually owns the product with a documentation that helps them in a year from now.

It does not. For one thing, often the level of abstraction is not suitable for everyone (how could it be – people work on different levels of abstraction). Another thing is that you can't describe a system by only listing the user stories without documenting the resulting decisions in some way. In this sense, having the user stories is necessary but not sufficient.

Think about creating a documentation around the other artifacts of your product as well. In an agile manner. When you create them. In a way that is lightweight, but strong.

And remember to refactor your documentation as well.

till next time
  Michael Mahlberg