How to write clear software development requirements

Writing is thinking. To write well is to think clearly. That’s why it’s so hard. – David McCullough

Writing clear software development requirements is an art that can save you untold amounts of frustration and pain.

What are User Scenario & Acceptance Tests? Why do they matter.

User Scenario & Acceptance Tests (US&ATs) are the most detailed level of business requirement development from the Product Owner or Product User perspective. The combined output from one or more US&ATs results in a component product (epic) or new feature.
The technical team uses the US&ATs as the source of information to define their tasks in order to deliver the expected output of each US&AT.

When do we gather information and write up the User Scenario & Acceptance Tests?

The information for the US&ATs is gathered through the discovery process at the beginning of the project and then documented in the design process. You may also use the concept of rolling wave planning, where by you also write-up and refine US&ATs before sprints or at the end of management stages. This enables you to leverage the knowledge gained during the build process to update and improve US&ATs.

The relationship of the User Scenario and Acceptance Tests to the component products

The pattern for a User Scenario & Acceptance Test

In order to create a well-formed US&AT, we use tested and proven patterns to ensure that we document our needs in a consistent way that can be understood by others. Do not be fooled by the apparent simplicity of these patterns, I have seen people give up in frustration trying to create well-formed US&ATs

User Scenario
As a (role) I want/need (ability/feature ) so that (benefit).

Acceptance Test
Use either of the two patterns below to describe each test.
As a (role) I will (specify the action/event ) to confirm that (Ability/feature ) does the following (expected outcome).

Given (one scenario and related conditions) when (specify the action/event ) then (expected outcome).

What must a well-formed US&AT be?

  • Understandable
  • Independent
  • Negotiable
  • Valuable
  • Estimable
  • Small
  • Testable

  • What does a well-formed US&AT do to help you deliver results?

    • Define a unit of work that can be added to a sprint backlog / work package for each sprint or iteration
    • Communicates at a detail level what the person ordering the functionality/behaviour wants
    • Communicates how the developed functionality/behaviour will be tested for acceptance.
    • Use a standard pattern to give structure and completeness.
    • Explicitly state quality expectations.
    • Define and understand what the term “Done” means for each User Scenario and Acceptance Test
    • States what is important in the least amount of space necessary so that we make clear what is necessary for there to be a good understanding of the specific feature or behaviour.

    What does a well-formed US&AT NOT do?

    • Describe the tasks required to implement the required behaviour or feature. How a behaviour or feature is implemented is described in the Tasks. Tasks are developed by the production team when they carry out the Tasking exercise and is the fourth level of planning.

    What can we use a well-formed US&AT for?

    • Eliminating unpleasant surprises and broken promises. The cause of many difficulties between client and supplier is rooted in conflicting or ambiguous expectations.
    • One version of the truth
    • Assists the person ordering the functionality/behaviour to clarify in their own mind exactly what they want.
    • Make sure that all the functionality required is requested and the sum of the US&ATs will result in the expected component product.
    • Support a strategy of implementing effective communication across organisation and cultural boundaries.
    • Starting the process of quality management at the beginning of the requirements development process.
    • Identifying what is critical for the business value and what is nice to have, thus enabling scope tolerance management as well as cost management.
    • Define business rules and how they will be substantiated with acceptance testing
    • Identify and allocate accountability.
    • Conflict management. By following the rule that if functionality/behaviour is not written as a US&AT then it has not been asked for.
    • Quality review of functionality/behaviour during each iteration.
    • Performance measurements based on the Story points for completed US&ATs that have passed quality review.
    • Management of WIP (Work In Progress)
    • Ensuring that all work done adds value to the system and process. EX. Reducing defects, Reducing waste
    • Used as help documentation for new users of systems.

    One version of the truth, avoid confusion and conflict

    By documenting your detailed requirements using the US&AT Pattern, you will avoid misunderstandings resulting from multiple discussions and people have different interpretations on what was agreed.