We have just started a new project to a customer who sells widgets. This customer is the leading widget provider of the whole world so the project can either make or break us.
The project uses agile methods, and the Product Owner has come to talk with the team. He is going to describe the most important feature of the application to the team.
Product Owner: This application is essentially a website which showcases the widgets sold by the customer. The most important function of this application is the add new widget function.
Team: That makes sense. After all, the application cannot showcase anything until widgets can be added to its database. Can you show us the specification of this function?
Product Owner: Sure. Here you go.
The Product Owner shows the following figure to the team:
Let's stop here. Does that figure answer to the following questions:
- What is the goal of the feature?
- What are the steps required to add new widgets to the database and what happens after a new widget has been added?
- What kind of errors can occur and how these errors should be handled?
No. We can figure out that the goal of this feature is to add new widgets to the database. However, that figure doesn't answers to the other questions.
Is that figure really a sufficient specification?
NO! It is just an UI mockup for crying out loud! It is not a specification!
But it is an idea. We can work with it and transform this idea into an agile specification.
From Idea to Specification
The biggest problem of the situation where the team gets incomplete specifications from the Product Owner is that the team cannot really implement anything before they figure out what it is that they have to implement.
This means that the team has two options:
- Ask additional question from the Product Owner
Both of these options are problematic.
If the team decides to continue dialogue with the Product Owner, it takes time to figure out the exact requirements. This means that they are not writing as much code as they could write.
If the team decides to improvise, they are essentially guessing what they have to implement. What happens if their guess is incorrect? Exactly. They have created waste and they have to reimplement the feature.
In other words, incomplete requirements kill the velocity of the team!
If the Product Owner truly wants to maximize the velocity of the team, he must deliver Enabling Specifications to the team. The role of the product owner is described in a Scrum pattern called Enabling Specification:
The Product Owner should deliver enabling specifications as a sign that he or she has done due diligence in exploring the requirements space. "Enabling specification" means that the specification is rich enough that someone reasonably skilled in the discipline can implement a solution without substantial subsequent clarification.
When the Product Owner delivers enabling specifications to the team, the team transforms these requirements into code.
From Specification to Code
When the team gets an enabling specification, the ball is in their court. They have to figure out how to implement that specification but that is not all they have to do. They have to ensure that their code fulfils the requirements of the specification, and preserve the specification so that the next person who runs into their code knows what it is supposed to do.
The problem is that no one really reads the documentation or updates it. That is why writing documentation is clearly not the answer.
There is a clean solution to this problem:
We have to transform Enabling Specifications into Executable Specifications.
The most hyped way to do this is to use Test-Driven Development. To be honest, I don’t care whether the team writes tests before or after they write the code.
What I care about is that the team follows these guidelines:
- The team must use end-to-end tests (aka integration tests) specify the requirements of the function.
- The team must write unit tests which specify the requirements of each layer.
If these conditions are met, the team has created Executable Specifications which can be run at any time.
This gives us two big benefits:
- We will know immediately whether the software fulfils its requirements or not.
- If we want to know how a specific function is supposed to work, we can read the end-to-end tests and find it out.
We don't have to spend countless hours of reading outdated documentation and gather nuggets of information from other team members. All we have to do is to read the tests.
That sounds damn good to me.
Just Do Your Damn Job
The main idea behind this approach is this:
The requirements of our application are never lost and we can find them out at any time!
Following this approach is not easy. It takes a lot of work and DISCIPLINE to get everything right.
The Product Owner must own the product and help the team to provide as much value to the customer as possible. On the other hand, the team must ensure that requirements of the application aren’t lost during the implementation phase.
I have heard my share of excuses why this cannot be done but all these excuses have one common problem:
Our customer doesn't care about our internal problems. He is paying us a lot of money and expects to get a good return of his investment.
Isn't it our job to ensure that this happens?
Nice read and a very good summary of the current practice!
IMHO, the reason the team rarely reads or updates the documentation (specification) is because of the complete tool separation. After all, we (the developers) do update/write e.g. ticket comments etc. right? But updating a Word document after I closed a ticket just feels wrong (from a tool perspective). If you are interested, please take a look at agileSpecs (https://agilespecs.com). I am a developer of this software and we try to solve this tool-gap for agile teams.
I agree that using Word documents is the best way to ensure that A) you have to spend a lot of time enforcing that developers update the documentation or B) accept that documents aren't updated. I have written more about this in my blog post: Writing Just Enough Documentation.