This is a “just enough, just in time” concept.
Just enough documentation to enable the implementers to implement it, delivered ‘just in time.’
Note: Jeff Sutherland prefers to refer to this as an Enabling Spec now, not an ‘Agile Spec’.
It is something written that the PO gets 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.
I think it is easiest to think conceptually at this point. 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.’ And being checked for ‘ready, ready’ before the Sprint Planning Meeting. But 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.
Any one Enabling Spec 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 the usual useless you used to include in specs, that no one read.
It does not say all the stuff they already know well. It is not trying to be ‘comprehensive’.
We are not ‘managing through documentation.’ Consider this sentence, repeated 15 times, 15 different ways.
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, who maybe had too much fun in college, we need to write or draw more.
For some people, who maybe took their Ginkgo today, we need to write or draw less.
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.’