Agile – How to Convince Team User-Stories Replace Requirements Specification

The typical story template is very easy to visualize:

As a [ROLE] I need to [WHAT] so that/because [WHY].

The interesting thing is that the importance of the components are reversed.

WHY is more more important than WHAT and that is more important than ROLE

Example using this Question

As a Software Developer I need to learn how to write User Stories so that I can populate the backlog with drafts to get discussions of the features started and get points assigned to them.

Anything more is over complicating the intent and the implementation of User Stories.

Additional Tools ( Integration is best )

Tools can be used to capture additional detail information about the stories that is captured when discussing them to assign points/estimation, but that detail should not be part of the story itself. Something as simple as a Wiki with 1 Page per story to put details/transcripts of discussions on is a good enough solution. Excel spreadsheet is a terrible solution.

I think the best approach to this would be to first provide a unique identifier to your state transition diagram. This will allow it to be referenced in downstream work. It would also allow your specific requirements to be explicitly linked to the figure, providing traceability between a visual model and a textual requirement, even if they live in the same document.

When you're creating textual requirements from the diagram, don't just translate the diagram to lines of text. In Visual Models for Software Requirements, the authors suggest asking four questions to derive requirements from a State Table or State Diagram:

• What conditions are required for the transition to occur?
• What action initiated the transition?
• What is the output of the transition?
• What actions or data transformations occur as a result of the transition?

The above diagram comes from the Seilevel website. The leadership of this company, Joy Beatty and Anthony Chen, wrote the book I linked to above. This example also appears in Chapter 23 of the book.

From a diagram like this, you can derive some functional requirements. For example, you know that your system shall accept a property address. There could be a data dictionary that describes that address's format that you can reference. I suspect that there would be some defined interface for the electronic transmission of an application. You could also reference an Interface Requirements Document or Interface Control Document that specifies the formats for inputs and outputs, if one exists. You can derive some roles and responsibilities from this diagram as well, that could go into a Roles and Responsibilities Matrix that can be created to say who can deny a submitted application. There could be business rules related to the application processing that can be functional requirements. If there is automated processing, you can derive non-functional requirements for the processing state, such as time.

Your "shall" statements would not just be an enumeration of this diagram. They wouldn't be things like "the system shall start in a prequalified state" and "the system shall transition to a submitted state when the property address is entered". Instead, you would use this as a tool to clearly see business rules and functional/non-functional requirements. It would especially highlight the requirements that are missing - what if you don't have a definition of who can perform the state transition from submitted to denied?