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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s