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:
- This is not a user story. This is an epic which needs to be decomposed.
- 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:
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.
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.