The Agile Manifesto extols the virtues of working software over documentation as a true measure of progress and business value. Teams in the early stages of agile adoption sometimes misinterpret this to mean that they should not write anything down. Other teams that are accustomed to waterfall and documentation-heavy methodologies continue creating extensive and redundant documentation under the guise of User Stories and Acceptance Criteria.
Lean Agile Requirements is a middle ground that provides a framework in which complex requirements are captured in living documents that speak to many audiences and serve a purpose beyond the initial development of the application. The flow for discovering and capturing these requirements in the process of developing new software appears in the diagram below.
User Story Writing Workshop
Product Owners, business representatives, and the development team meet to identify user stories. User roles are identified and a couple of sentences are written to describe the goal and value of each story. Stories are mapped into releases and become the basis of the product backlog.
Grooming conversations occur at regular intervals in advance of the sprint in which a story is actually turned into software. In grooming, a user story may just contain a couple of sentences describing the feature increment. Each story is discussed and the UI might be sketched on a whiteboard or in a UI mockup tool. Acceptance criteria also may be identified – these are high-level user acceptance test cases (hint: these are not detailed tests, yet) but are only discussed/captured to the extent needed to size the story.
Sprint planning conversations are where the team starts to think in more detail about how it will build the feature increment described in a story. The discussion becomes more detailed but it is important to avoid getting into too much detail too soon (e.g. avoid things like “Should we show transactions that are less than or less than or equal to the Invoice Date?”). Any details that do surface can be captured as the initial User Acceptance Test Cases but they are not always necessary at this point. The technical design is reflected in the tasks and estimates that the team creates. Note that the user story itself does not need to contain any of this additional detail.
What is a User Acceptance Test Case?
Acceptance Test Driven Development (ATDD) is based on the premise that one of the most effective ways of communicating requirements is by understanding how the user will use/test a feature and the expected results. Acceptance tests avoid many of the pitfalls of business rule statements because they eliminate the layer of interpretation and ambiguity involved in understanding the outcome of a business rule in various scenarios. Writing these tests is as simple as asking the user “What tests will you run to validate this feature?” The test cases capture the user’s actions and expected results using real examples as much as possible. For the developer, it is like having the answers to an exam before taking it.
When the team has pulled a user story into a sprint, the first step in working on the story is to meet with the users and detail the user acceptance test cases. This is when and how detailed requirements and behaviors are captured. Note once again that the user story itself does not need to contain any of this detail. The detailed user acceptance test cases are then used by developers, QA staff, and users to create and validate the working software.
Once the feature is deployed to production, bug reports that are handled as support tickets may uncover additional user acceptance test cases. As the one living document that the team maintains, the user acceptance test cases are updated as the software evolves. They are used to run regression tests to make sure that other functionality is not impacted by the defect correction.
By capturing complex requirements in the form of user acceptance test cases, the team can build and maintain a product with the confidence that the user’s needs are being satisfied.