Saturday, June 02, 2012

Enabling Specifications: The Key to Building Agile Systems

Previously, I discussed the notion of "Agile Requirements" and this concept is embedded in the Nokia Test. There is not a definition of Agile Requirements that is commonly agreed upon, so I now use a standard concept that is better terminology for what is needed.

For many applications, particularly web applications, a story only needs notes and acceptance tests on a card or sticky note. For some applications, like mobile applications for physicians, unless a fully formed prototype is acceptable to a carefully selected group of test physicians, end users will refuse to use the application when it is installed in the hospital setting. Therefore, a fully formed enabling specification, with a fully working prototype, needs to be agreed upon before cutting a line of code.

Apple uses this routinely which is "Why You Can't Innovate Like Apple." PatientKeeper used this strategy during 2003-2008 which is one of the reasons they were the fastest company-wide set of Scrum teams I have ever seen. I called them "The Future of Scrum" at Agile 2005. Some people said PatientKeeper looked more like Kanban than Scrum so they were also the fastest Kanban teams ever seen. I have always run Kanban inside of Scrum since 1993 since Scrum is Takeuchi and Nonaka's view of lean teams. However, we tried to minimize the Kanban, just as Taiichi Ono did and as Toyota does today.

In 2007, I visited PatientKeepers patent attorneys as our CEO wanted to get a patent on a discovery of a reporting strategy for analyzing physician fee payments that would raise hospital revenue by 30% during the first month of use. I asked the Product Owner to bring along what documentation she had for review by the lawyers. There was a three page Agile Specification. This is a document that Product Owners at PatientKeeper use to describe the global concept of a feature. User stories are developed from this document.

Our goal was to work with the lawyers to understand how much documentation was needed for a patent application. The lawyers pointed out that a patent application is an "enabling specification." This is a legal term that describes a document that allows the average person knowledgeable in the domain to create the feature without having any discussion with the originators of the enabling specification.

The lawyers determined that our Agile Specification of three pages was not an enabling specification. To produce a document that would be approved by the U.S. patent office we would need five pages.

It turns out that an enabling specification is exactly what is needed to maximize the process efficiency of executing a user story. The average process efficiency of teams executing user stories is about 20%. This means a story that takes one ideal day of work takes five calendar days to delivery. Systematic Software Engineering, a CMMI Maturity Level 5 company, has extensive data showing that teams that drive story process efficiency to over 50% will double their velocity systematically for every team. (PatientKeeper was running at 10 times the velocity of our waterfall partner in India.)

The definition of an "enabling specification" is part of U.S. patent law which has been adjudicated extensive by the courts so it is not only a commonly agreed upon concept, you can take your requirements to court and the judge will tell you whether or not they are enabling specifications.

In general, requirements are NOT enabling specifications. On a recent project at a large global company we discovered that hundreds of pages of requirements were not enabling specifications. On the average 60% of what was in the documents was useless to developers. It caused estimates to double in size. Even worse, 10% of what was needed by developers to implement the software was not in the requirements.

The enabling specifications used at PatientKeeper provided a global description of a feature set framed as lightweight user stories with screen shots, business logic, and data structures. The enabling specification was used to generate user stories which then formed the product backlog. The global feature description was updated regularly by the Product Owner team and was a reference to the state of the system that allowed developers to see where the user stories in the product backlog came from.

A user story needes to be a mini-enabling specification for agile teams to operate at peak performance. If it is not, there will be the need for continued dialogue with the Product Owner during the sprint to figure out what the story means. This will reduce story process efficiency and cripple velocity.

A user story contains a template, notes, acceptance tests, and implies a conversation with the Product Owner. So the conversation may be part of the mini-enabling specification if the conversation is clear before the beginning of a sprint. This can be on a card for a simple application and will be on the order of no more than 3-5 pages even for a complicated mission-critical and life-threatening application like the PatientKeeper Platform.

As the lawyers pointed out, an enabling specification for a major feature needs to be no more than five pages. So all of the documentation needed, including transcribing all the conversations, should be on the order of 3-5 pages for a moderately large feature. This is what I mean by "Agile Specification." I now think "Enabling Specification" is better terminology.

2-231 Obtaining Patent Rights  § 2.07[6]
"A patent specification is enabling if it allows a person of ordinary skill in the art to practice the invention without undue experimentation."

See Jay Dratler. Intellectual Property Law: Commerical, Creative, and Industrial Property, Volume 1 for citations.


Robert Dempsey said...

Great post Jeff. I'm definitely going to share this with everyone I know.

Many people that look at Agile say that there is no documentation. What you have listed as required for a user story - acceptance criteria et al. - I feel is the documentation that is required for the team to successfully create the value of the story. Having a story as a standalone item means information. We just don't need to have all that detail until close to the time we're getting ready to make it happen, IMO.

Jürgen Rohr said...

Thanks Jeff. This post is realy helpful.

It would be great, if you could give an example of an enabling specification to get a better feeling for the level of details that should be covered ideally.

Dave Rooney said...

Indeed this is a great post, especially the quantification of the waste in traditional requirements documents.

I'm curious, though, about the 20% efficiency figure for User Stories, and "1 ideal day takes 5 calendar days to implement". Do you have a reference for that? What about teams that are using Points as their unit of measurement?

Dave Rooney
The Agile Consortium

Tobias Mayer said...

Hi Jeff, are you suggesting that each user story needs a five-page document to accompany it? What you are describing here sounds like a hand-off, which I feel is at odds with an Agile approach. I might describe this as "small-design up front", which would be different, I think, to emergent design, which is more of a continuous dialog.

My understanding of a user story is that it is indeed intended to generate dialog. Certainly much of that dialog can (and should) take place before the sprint but sometimes it is necessary to have continued dialog throughout the sprint. In fact, I have seen teams move much faster when they do this, AND deliver the right thing at the end.

A PO embedded in the team is a powerful thing.

Jeff Sutherland said...

There is good data on story process efficency in my Give Thanks for Scrum Day presentation. See

Jeff Sutherland said...

My point here is that a large story needs a maximum of five pages to document essential details. Most of these can be a conversation with the Product Owner. However, in certain applications with life threatening implications, teams find that a few things need to be written down to make sure everyone remembers them correctly. Like what dose of this drug will kill a patient and when a physician must be alerted.

Dave Rooney said...

OK, so the 5 pages records the conversation, but doesn't replace it. That's what I've been telling teams for years now - documentation is great for archival purposes, but it's lousy as a communication tool.

Tobias Mayer said...

Fair enough. No disagreement on that. I agree a team needs to understand what they are undertaking. I use the term "well-formed outcome" (from NLP) which likely means the same thing as "enabling specification".

There are times it is essential to get this in writing, often it is better to talk and confirm as we go. Different contexts dictate different behavior. If I had a web dev team working on a non-life-threatening app I'd be very concerned if they had 5-page specs.

Phil said...

Very interesting concept 'enabling specification' - thanks for presenting this.

One of the few (maybe the only) references I've ever come across that mentions 'transcribing all the conversations'. I like this. Conversations are great and are a cornerstone of the agile approach to collaboration on requirements but people's memories of the conversations can easily diverge. Of course that brings up the whole question of the fidelity of the 'transcribing' process. In some cases a high fidelity 'recording' might be a useful approach (i.e. audio or video), perhaps not for the lawyers but maybe for the team.

mad-z said...

Pretty good I will say. By definition "Enabling Specification" would mean enough specification that would enable to the team to start thinking towards producing the desired out put. If something is missing, go add it.

Tobias, I do not believe Jeff is proposing a 4-5 page specs for each story - but mentions about a moderate size feature. The number of pages are for you to decide. As long as it ENABLES, I think it is good enough.

Randy Tangco said...

I want to ask about the 'transcribing all the conversations' part. How are we going to do this? I know that one way to capture conversation is to record them but is this something you can freely do and use it later for the purpose of transcription?

Jeff Sutherland said...

Transcribing the conversations for the development team in necessary only to the extent that critical information needs to be captured. The Product Owner determines what to write down based on the development teams questions during an estimation session. Anything the development teams knows need not be documented. For patent applications a little more thought about this is necessary.

Robert costello said...

I am big proponent of using a BDD approach both in its structure and in the thought process especially when eliciting stories. For me if the acceptance criteria is fully
articulated, then wouldn't you have an enabling specification.

Robert costello said...

I am big proponent of using a BDD approach both in its structure and in the thought process especially when eliciting stories. For me if the acceptance criteria is fully
articulated, then wouldn't you have an enabling specification.

charlesbradley said...

The tone of this article, as well as the InfoQ article referencing this article ( ) smacks too much of 'documentation' and not enough of 'discussions,' in my view.

For each team, there is an optimum "Goldilocks Balance" of how much documentation should be created.

The tone of this article is that the PO should create a user story "document" and then the developers should never have to talk to the PO during the Sprint. To me, this totally violates the User Story principle that a User Story card is a "reminder for conversation" with the PO and/or users.

I realize that the tone I describe may have not been what was intended, but it's my perception from reading it.

I always thought an "Agile Specification" meant automated acceptance tests -- but I could never figure that out from reading the Nokia test -- so I just did some Google searches and guessed at what it meant.

In any event, a User Story is a card/token/reminder for conversation, the conversations with Users and/or PO's, and test confirmations (that are preferably automated). None of that directly implies "document", and yet this article does -- strongly in my view.

I totally concede that some industries(team contexts, etc) will need a certain amount of documentation.

I think we should focus a little more on defining the "Goldilocks Balance" of the optimum amount of documentation for a team.

This is one reason I kind of prefer the "Definition of Ready" concept over the "Enabling Specification" concept. In fact, I just don't think I like the word "Specification" at all -- way too old school for my tastes.

Just my opinion, of course.

Jeff Sutherland said...

A good Product Owner is talking daily with the team so this blog item is not meant to remove the product owner from the discussion. However, at Scrum Inc, the velocity of the team tripled by having good user stories that were understood by the team before implementation so having good user stories is critical. Most Scrum teams will tell you their user stories are not good so their velocity is 30% of what it should be. However, this blog item addresses mission critical requirements that must be documented for user, safety, legal, or compliance reasons. Patents average about five pages so most requirements should never exceed five pages, not a lot of documentation. A recent FDA certified medical device had 13000 pages of documentation reduced to 800 by Scrum, most of it automated. The Scrum coach send he thought he could eventually get FDA to agree to 300 pages. So this would be almost 100 times less documentation that a typical waterfall implementation of such a product.

scrumcrazy said...

Thanks for the clarification, Jeff.

1. I worry about statements like:
"...most requirements should never exceed five pages..."
While I think it is a true statement, it kind of implies that having 4-5 pages of requirements for each user story is ok, when I believe that to be ideal in only about 5% or less of applications and team contexts out there. Again, I think we need to encourage people to strive for the "Goldilocks" balance instead. Recent advice by Ron Jeffries(co-creator of the User Story technique) have pointed to user stories that last no longer than 2-3 days. It's hard to believe that you'd need 5 pages of documentation for 2-3 days of programmer work, but I'm sure there are extreme cases of this. If there are extreme cases, I think we need to label them as extreme.

2. Further, in your article, you say:
"This can be on a card for a simple application and will be on the order of no more than 3-5 pages even for a complicated mission-critical and life-threatening application like the PatientKeeper Platform."

I have seen very complicated applications that use only a story card because a) the team and PO are highly interactive on a daily/hourly basis and b) the stories are kept small (a few days).

3. By recommending the 5 page limit because that's the limit for patent applications, what you're saying is that software requirements and patent applications are roughly the same or take roughly the same amount of time because they are such similar topics. I didn't mind your "Enabling Specification" analogy in the patent world, but when you adopted the exact same page limit and said we should do it in the User Story practice, you went further than an analogy and somewhat equated the practices. Whether this is truly applicable or not -- I'm not sure -- but what I can tell you is this: Patent applications are meant to exist on their own and without the aid of others in understanding. User Stories are "promises for conversations", so they are quite reliant on the aid of others for understanding, are quite different, IMO.

4. The sad part about all of this is that I agree 100% with what you're trying to say. I'm just not sure that the message will get across as you intended. People in the Scrum world are fond of saying "Jeff Sutherland said 'this'..." and "Ken Schwaber said 'that'..." Many times they are taking things very much out of context or misunderstanding them, so I really think the Scrum thought leaders should be careful about what they say to an internet audience.

In short, I think your post will come across to the casual Scrum reader as "Your user story documentation is fine, so long as it's not more than 5 pages per story, and so long as it doesn't require any material communication with the PO during the sprint (sub message -- no need to communicate with the PO during the sprint)."

Dennis Stevens said...


I like the term enabling specification. I have been saying barely sufficient specification to enable effective conversation.

The specification may not be developed up front by the product owner - but collaboratively among the right people. The specification serves to enable and reflect the conversation. I include the specification as part of the conversation (the 3 c's).

Finally, I give guidance that the reason for decisions is at least as important as the decisions. While the decision can be defined in the Acceptance Criteria (the confirmation) - the specification should remind everyone of the reason for the decision. That way, when we continue the conversation in the sprint, we can pick the conversation up in context.

One other note. I really struggle with the interpretation that an upper bound on something automatically becomes the target. Or that producing some documentation means that there is a hand-off. I didn't sense you reflected any of that any of that in your post.

Philip Wess said...

Hi Jeff,

Great Article and follow up from our class discussion on 5/31- 6/1. Does anyone have a good recommendation on some Kanban books and materials?

Thank you - Philip Wess

Philip Wess said...

Hi Jeff, Great article as a follow up from the 5/31 - 6/1 CSPO class. Does anyone have a good recommendation for some books on Kanban?

Thank you - Phil Wess