This is a “just enough, just in time” concept. As some of you know, just-in-time (JIT) was one of the first names for what we now call Lean.
Just enough documentation to enable the implementers to implement it, delivered ‘just in time.’
This is closely related to the “Definition of Ready” or DOR concept. Which is essentially the same as the ready-ready concept and the ready-ready criteria.
Note: Jeff Sutherland prefers to refer to this as an Enabling Spec now, not an ‘Agile Spec’.
The PO is responsible for getting this Enabling Spec done for the Implementers on the team. The Implementers define exactly what they need, and the Enabling Spec is neither more nor less than what they need to get it done right. Quickly. High quality. Etc.
What might it contain?
The useful things.
Imagine a 1/2 page (or 1 page or maybe 2-3 pages, if the drawings are big) tied to each small, sprint-sized user story.
It is simplest to think of the Enabling Spec being written or drawn or created ‘one sprint ahead.’ Or maybe over two sprints. (This partly depends on your organization and the types of stories you are doing.) And the Implementors check the Enabling Specs before the Sprint Planning Meeting. And the Implementors can reject a story if the Enabling Spec is not good enough. Why waste time on an ill-defined story?
(Yes, there can be a reason. For example, the PO judges that the only way to clarify ‘this’ story is to build something, and get feedback from that. But hopefully, that is relatively rare. Again, how the PO and the Team and the Organization attack this issue depends on many factors.)
Your real world may require some common sense adjustments to that. Be careful; common sense is remarkably uncommon.
Maybe hand-written. Maybe on a wiki. Maybe in a Word doc. Maybe put in different ‘fields’ in Jira.
Who writes it? The best people of course. Self-organize! But clearly the PO is responsible for getting the right information into the Team.
It might hold:
- the acceptance criteria
- a business flow
- a list of business rules
- a wire frame(s)
- a mock-up of the screen (if that means something different to you)
- a simple use case (probably not all the darn UML use case stuff… just something, just enough) (to me, this is a variation on a business flow, using a few specific symbols)
- a data flow
- new data elements (or whatever you guys call them)
- key data elements and key values in this context (for this story)
- a screen flow
- a simple design picture
- an example (eg, if X, Y, Z inputs, then we expect A, B, C outputs)
- test scenarios (enough so they understand the tests)
- anything else they may find useful to build it quickly and for it to EXCITE the customer
[Each team should make a list like this of the ready, ready criteria.]
Some of the items above might be considered redundant. Use the terms that work for you. Make sure the Team is clear in what each term means.
Any one Enabling Spec (for a specific story) will NOT have all of these things. You must pick and choose, based on your Team, the product and the story involved.
The Enabling Spec does not repeat information they have, even if in the past it was common you included that information. Do not build pages no one will read. Only the new stuff, the as-yet unknown information. (OK, if you think they might forget or you see that it is necessary to connect the dots, as we say, then add it and ask the Team if that helped.)
It does not repeat information they already know well. It is not trying to be ‘comprehensive’.
We are not ‘managing through documentation.’
We are sharing knowledge in one effective way. It is not the only way to share knowledge, and create knowledge. Two people at a white board should still be used a lot.
And we definitely use the Enabling Spec as a basis for conversation, to confirm that everyone is seeing the same elephant (in this case, the same small, sprint-sized user story).
For some people, you may need to write or draw more.
For some people, you may need to write or draw less. Depends on your Team.
Over time, the list of ‘things we should typically include’ will change. We will learn that some stories will be done wrongly if we don’t include X. And we will learn that they never read Y. So, your team should create its own living list of ‘things you might include in an Enabling Spec.’