Defining "Done" in User Stories
by Victor Szalvay
January 6, 2010

An increasing number of organizations are taking the plunge to Scrum, with or without professional coaching. Developers transitioning to Scrum can avoid many pitfalls by following a handful of hard-learned principles. In this article, I discuss a common mistake with the popular "user story" requirements format: poorly defined done criteria.

I've seen a lot of Scrums over the years: Good Scrums, bad Scrums, and everything in between. Sometimes the Scrums are productive, transformative machines, but, in other cases, Scrum simply means walking through the meeting mechanics, following the basic rules, and an attempt to incorporate basic Scrum roles.

I believe the secret is to embrace Scrum’s focus on quality. Too many development groups are doing Scrum without baking quality into their products from requirements to deployment. The results are faster development of the "wrong product" and an accumulation of unmaintainable code, which ultimately leads to reduced velocity as technical debt builds up. Conversely, a quality product addresses market needs, and the ease of maintainability means that velocity isn't weighed down by cumbersome code.

So how do you bake quality into your product? While that's too broad of a topic to cover here in detail, I've found one commonly overlooked thing that often qualifies as an excellent first step:

To succeed with Scrum, you must clearly define what you mean by "done."

The Importance of User Stories

I'm referring to user stories or product backlog items in sprints. Before a team sets out to work on user stories in a sprint, the team and Product Owner must have a clear agreement on what it means for each work item to be accepted as "done." This agreement is pivotal to Scrum: without it, you will find only frustration and miscommunication.

A user story should set the stage and provide some context, but the definition of "done" in a user story is the meat of the contract between the development team and the Product Owner. I usually structure product backlog items as follows:

User Story: As a registered user, I want to reset my password, so that I can log in even though I've misplaced my password.

Definition of Done:

  • Provide a "password reset" option
  • User must provide valid email address of a registered user to reset password
  • User must demonstrate control of email address to reset password

So why is this so hard to get right? You can go wrong by going overboard in either direction. Provide too little detail and you end up with sprint review meetings where expectations are not met or the wrong product is built. Give too much detail and you're struggling to get started because your user stories are over-analyzed.

The Right Level of Detail

Let's start with the first case: too little definition. This one is pretty obvious: if there's any room for interpretation, you can bet that the team and Product Owner will have diverging conceptions of what "done" means. The team has a natural incentive to minimize the scope of product backlog items, while the Product Owner typically wants as much stuff built as possible. These incentives lead to misconceptions in terms of what qualifies as "done."

Tracking our example above, here's an example of an under-developed definition of "done:"

Definition of Done:
  • User can reset password if lost
  • Password reset based on user's email address

See why this is a recipe for disaster? It leaves out too many details around the verification of a user's account before resetting the password. Unless your team is particularly gracious and/or motivated, you'll likely see a sprint review demo without email address verification. Perhaps that's what was agreed upon, but likely there will be a lot of head-scratching at the review meeting. Maybe you're excited that your team built anything at all, but that's another story...

Now let’s consider the opposite problem. Perhaps you're an analytical go-getter of a Product Owner. That's good. But it can be counter-productive and detrimental to the Scrum framework if you go too far over the top when you define done. Here's an example:

Definition of Done:
  • Password link appears on X, Y, and Z screens under the fourth table using font "Snazzy," HTML color #0044fe
  • User must provide valid email address of a registered user to reset password
  • A message will be emailed to user asking them to click a link to verify email account ownership
  • The message contains instructions to ignore the request if it wasn't requested by user
  • The message contains legal disclaimers and opt-out information
  • The verification scheme will use a unique hash key stored in a database table user_request_reset
  • The db table is purged every 30 minutes for security reasons
  • The db table schema is built to spec using proper foreign key constraints etc...

You may be thinking that all this detail is actually rather good. The reality is that you will not get through sprint planning in half a day if you've pre-written all your product backlog items in this level of detail. You will get differing opinions and discussion on each and every point as your team will often provide insights for improvement that negate a lot of the details you spec out in advance. Remember that in Scrum detailed requirements analysis happens during the sprint, not before and not during sprint planning.

Another issue with the above example is that it details things like db schema, stuff that's meant to be left to the team to decide since product backlog items define "what" is to be built, not "how." That is to say, let your team handle detailed requirements during the sprint and let your technical folks handle implementation details.

So what is just right? You need enough to get exactly what you want without overloading it to the point of detailing implementation details. In our example, here are the main things I want to see in the finished product at sprint review:

Definition of Done:
  1. There needs to be a link or some way to get to the password reset screen. I accomplish this with:
    Provide "password reset" option

    Notice that I'm not implying a UI. It's generic enough to allow for detailed UI-specification later during the sprint while ensuring I get what I need.

  2. The password reset function works by taking a user's email address. I accomplish this with:
    User must provide valid email address of a registered user to reset password

    Again notice that I don't specify implementation details, only my purpose.

  3. The user must first demonstrate control of the email account before a new password is issued I accomplish this with:
    User must demonstrate control of email address to reset password

    Here again I've avoided lengthy and detailed specifications regarding the exact implementation, but I've made the security protocol clear nevertheless.

It takes a bit of practice to find the sweet spot with "done" criteria. Once you have it down you'll see an immediate impact with your Scrum teams as they gel around clear, actionable goals.

There's another important dimension to being "done." Explicitly agreeing on the software's functionality is one thing, but what about the non-functional requirements? How do you ensure that the team isn't cutting corners on quality or getting the product into technical debt to make it happen? I’ll answer those questions in a follow-up post, so be sure to check back soon.


Danube Technologies

Technical Debt and Design Death [PDF]

INVEST and SMART User Stories

How Do We Know We Are Done?

Talk back!

Have an opinion? Readers have already posted 2 comments about this article. Why not add yours?

About the author

Topher Cyll is a software engineer in Portland, Oregon, who’s lucky enough to write about half of his projects in Ruby. Topher wrote the Multiple Dispatch and S-Expression RubyGems used in this article. He also volunteers on the Tech Team of the progressive political group The Oregon Bus Project and is an active member of the Portland Ruby Brigade.