We have written user stories such as:

As a small business owner
I want simple and easy instructions to follow for any recommendations to my website
so that I understand what it is I need to do and what resources are required.

How do I measure simple and easy instructions within the acceptance criteria so that I can prove that our solution works?

5 Answers 5


I think subjective user stories are a recipe for scope creep. If you want to focus on business owners requirements & make something that is measurable then I would fall back on a framework like the Digital Marketing & Measurement Model for generating discrete KPIs that the business owner will understand & are achievable from your point of view.


  • Objective: Better documentation
  • Goal: Usable instructions
  • KPI: Improve recommendation implementation
  • Target: 90% of recommendations are implemented within one week
  • Segment: Task backlog report

So the user story becomes:

As a small business owner I want simple and easy instructions to follow so that I implement 90% of recommendations within one week


Why Your "Story" Isn't Testable

As a small business owner
I want simple and easy instructions to follow for any recommendations to my website
so that I understand what it is I need to do and what resources are required.

You have two problems here:

  1. This is not a user story. This is an epic which needs to be decomposed.
  2. This story doesn't follow the INVEST criteria, which is why it lacks obvious acceptance critera. This is often okay (if not ideal) for epics, but you need to make sure the related user stories are testable.

Subsequent sections will discuss how to decompose your epic, write stories that follow the INVEST mnemonic, and switch to an iterative test-driven documentation model.

Agile Solutions for Making Documentation Stories Testable

Decompose Your Epic

The first thing you need to do is to decompose your epic into discrete user stories. Consider the following example:

  • Epic: Website User Documentation

    1. As a website owner
      I want the owner's manual to contain a chapter on configuring the captcha settings
      so I can increase the number of user login attempts required to login.

    2. As a website owner
      I want the owner's manual to contain a chapter on randomizing the landing page
      so I can make it difficult for users to bookmark my site.

These stories, while silly, are largely actionable. Each story contains a concrete deliverable (i.e. a chapter in the owner's manual) on a specific topic with enough context to provide measurable goals.

Define Acceptance Testing

Of course, part of your Definition of Done should involve testing whether the information in your manual is being properly conveyed. That isn't part of the user story; instead, part of your Sprint Planning for this story is to add any necessary user acceptance tests to your Sprint Backlog.

For example, the team may plan to have a real customer walk through the chapter on captcha settings, and see if it's understandable and complete. Or the team may choose to have a team member walk through the chapter, step by step, and follow the directions in the manual as opposed to doing it any other way to see if it works as written. This will most definitely provide useful feedback about the usability of the instructions.

Iterate, Iterate, and Iterate Again

Iterative development is not about getting something perfect the first time around. Perhaps you deliver your chapter on randomized home pages, which was understandable and useful for the tester at that time, but you later have a new customer who struggles with step 15 of the same chapter. From an agile perspective, this is simply an opportunity to incrementally improve!

You would write a new user story, such as:

As a website user,
I want Step 15 of Chapter 23 to be rewritten for clarity
so that I can follow the procedure for randomizing my home page.

Again, the goal and scope are well-defined, but the acceptance tests are adjusted. You should be adding tests that include acceptance testing by your new customer (or a proxy), while regression-testing with your existing acceptance tests to ensure you aren't making things worse for your existing customers.

Follow INVEST Criteria

Each user story you write should be:

  • Self-contained, without dependencies on other stories.
  • Estimable, so that the scope and the level of effort are understood by the team.
  • Small enough to plan, develop, and test within a single sprint.
  • Testable, with defined metrics. Objective tests are best, but "Ask Mikey if he likes it!" still meets the requirements of testability so long as the team has agreed on that as a useful way to decide if a story is "done."

If you write your user stories in this way, you will find that the team will have a much easier time identifying both the goal of the story and the success criteria for it. This then makes the implementation details (e.g. what to write for each section of the documentation) much more obvious to the developers and technical writers without having to concoct detailed specifications.

By working with the acceptance testers or end users within the sprint, both to define the acceptance criteria and to test them, you also ensure that you don't end up with the wrong thing at the end of the sprint. This shift to test-driven documentation can be challenging, but is really no different than test-driven code from a process point of view.


There are two approaches to subjective measurements in user stories that can work, depending on your circumstance:

1) Don't Use Them: In some cases, you can work out more concrete measurements with the stakeholders to replace the subjective ones with. They can be specific, like replacing "I want the page to load quickly" with "I want the page to load in 3 seconds" or relative like "I want to improve the algorithm to process batches 25% faster."

2) Focus on the the Conversation: Let's say you want an intuitive claims reporting process in your application. "Intuitive" is much harder to translate into concrete terms, so you might need to agree on some methods that the team will use like paper prototyping with a set of real users to find out which of a set of options is the best. This approach has the risk of dragging on for a long time, so you'd probably want to time-box it. Strictly speaking, this is more of a Spike than a user story, but it should help solve your problem none-the-less.


An Acceptance Criteria, identify clearly the purpose and the scope. In general I try to define what scenarios are in scope and what scenarios are not in scope. In this case and following customers feedback, I will try listing some use cases to define some of the possible paths.

As a rule an effective acceptance criteria is detailed / specific and unambiguous and we should not use subjective language.


Use a Spike!

A task aimed at answering a question or gathering information, rather than at producing shippable product. Sometimes a user story is generated that cannot be well estimated until the development team does some actual work to resolve a technical question or a design problem. The solution is to create a “spike,” which is some work whose purpose is to provide the answer or solution. - http://agiledictionary.com/209/spike/

Once the spike is complete, you should now have enough definition to create your user stories.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.