What agile documentation has in common with cooking
My client calls me and says: We're agile now – we don't need documentation anymore! I stare at the phone, dumbfounded, and think: Actually, he's right.
In the evening, I'm meeting a friend to cook. On the menu are rösti and salad. She tasks me with preparing the potatoes for the rösti while she takes care of the salad dressing. When the potatoes are ready, she discovers with horror that I've peeled them before cooking them. "It's so much more practical and quick," I thought. After 10 minutes of fruitless grating—the resulting mess reminds me of mashed potatoes—I reluctantly boil the potatoes a second time, this time with the skins on. While she prepares the dessert, I fry and season the rösti. She asks me for the spice mix. The only problem is, I can't quite remember the exact ingredients.
At that moment, it dawned on me: Even though we're now working agilely, documentation (the recipe) aids communication, and product documentation (documentation of the spice mix) is crucial for the future of our product. One could argue that, as in agile projects, we quickly identified and corrected our mistake. But if we had
relied on a recipe for our communication, the mistake wouldn't have happened in the first place. And if I had documented the spice mix while seasoning the rösti, we could have started from there next time and perhaps even improved upon it.
So what should be documented and how?
In an agile context, the principles have changed significantly compared to traditional projects!
We only document as much as necessary and as little as possible.
We no longer document for the sake of documenting, but because documentation is beneficial and promotes communication between the various parties.
And we create the documentation "just in time"
There is probably no single agile documentation format, but rather there are tools that are more or less suitable for the current situation.
For example, if we are in the initial phase of an agile project, it is helpful to create a story map at the epic level (menu planning). However, it is still legitimate
to use a context diagram or a class diagram if this promotes communication.
User stories are now used to describe individual requirements. Their major advantage is that the initial focus is on customer benefits rather than the solution itself. However, provided that considerations regarding customer benefits are not lost and the team finds this approach more effective, requirements can still be written using a sentence template.
For discussing detailed processes or issues, "recipes" like wireframes, BPMN, or Behavior Driven Development (business rule-based scenarios) are suitable. But Use Case 2.0 (a use case that is continuously developed) or UML activity diagrams are also effective tools. Just like cooking, it's not primarily the tool used that matters, but the result achieved. It's not crucial whether I whip the egg whites with a whisk or a food processor. What counts is my skill with the tool and the resulting outcome. Agile documentation is therefore a bit like cooking. We don't cook for the sake of cooking. Rather, we create value through the menu.
To ensure our menu is a success, we use the right kitchen equipment (tools) at the right time (just in time) and use as many ingredients as necessary and as few as possible.
And when we've adapted a recipe, we document the change in the recipe so we can build on it in the future. If we adhere to these principles, documentation in an agile context will also be successful.
Gabriela Meier
Perhaps also interesting for you: Navigating the methods jungle with Whirl of Methods
Do you want to learn the basics of RE or refresh your knowledge? Then we cordially invite you to our Academy.
Or would you prefer a course tailored to your team? Then get in touch with us.
