Sunday, May 18, 2014

User Story Writing Starter Kit

Prior to Agile coming into existence, I was fortunate to learn how to write requirements by Elemer Magaziner (i.e., business requirements) and Alistair Cockburn (i.e., use cases).   They provided various alternatives to writing clear requirements that were irrespective of methodology.
From this I learned that there is a strong benefit to establish what I term as the “requirements language construct”.  This construct helps you consistently document your requirements focusing on key requirements elements. One common requirements language construct in the Agile world is the canonical form. It is important to realize that elements of the canonical form have been around for years.   With that being said, the three basic elements of the canonical form provide a good framework for establishing requirements. 

First I will discuss the user story that is typically expressed within the three-part canonical form.   Then I will introduce the enhancement of a requirements language construct that can adapt the canonical form.  The language construct for a user story in canonical form looks like this:
The persona is the user type who will receive the value.  The action is what the user type desires.  The business value is the benefit to that user type.  Note: you can learn more about personas in the article Personas – Do you really know your Users?   The following are examples of user stories in canonical form:
  • As a learner (persona), I want to set up my profile to include my photo (action), so that my distributed team members know what I look like (business value).
  • As a prospective buyer (persona), I want to search on homes (action) so that I know what properties are available in my price range (business value).

As enhancements to this construct, you may consider adding the system that will be used or interacted with and the receiving entity which identified the expected output from the requirements.  If applying these, the requirements language construct would look something like this:

As a (persona)
I want (action) from (system) to the (receiving entity) 
so that (business value)

The following are examples of user stories with these enhancements.  The first example below takes the second example from above and enhances it with the system and receiving entity.
  • As a prospective buyer (persona), I want to search on homes (action) from MLS (system) to a separate window (receiving entity) so that I know what properties are available in my price range (business value).
  • As a quant analyst (persona), I want a derivatives report (action) from the asset management application (system) in the form of a pdf (receiving entity), so that I can distribute it to my fund managers (business value).

There is no “right” requirements language construct.  It is important to craft one and then experiment with it.  I would suggest starting with the canonical form and work from there. 

Finally, the Product Owner, Business Analyst, Product Manager, and anyone who writes requirements should be trained in writing user stories in whatever form is used to articulate requirements. The Agile Team should be educated in understanding what to look for in a user story and asking questions regarding the elements of the canonical form. You may also want to train stakeholders and customers on how to provide their needs in your requirements language construct for consistency and clarity. 

To read more about establishing an Agile Lagging to Leading Metric Path and Agile Measures of Success, consider reading Chapter 18 of Being Agile


  1. I, too, learned from Magaziner & Cockburn, and, adhere to their perspective on requirements as best as I can.

    I believe the enhanced construct you propose introduces too much solution. The writer should not know whether PDF is the best format for delivery. Nor, should they know whether it is good user experience design to display in a "separate window". These solution details are best left to discovery during the iteration phases. Alternatively, the user story can be written collaboratively with area expertise input to provide the details.

  2. Yes, I ditto Philip's comment.

    I was intrigued by your suggestion of adding "from" and "to" into the user story format. As far as "From" is concerned, wouldn't this always be the system(product) the team is building? if so, not sure whether there is a value adding this info. But, if you are thinking of "from" as the condition where the user is at within the system, then i think these could be best described in the acceptance criteria of the user story written in the format of "Gherkin" Given (pre condition or trigger ) when (action) Then (post condition or To in your example).

    what do you think?

  3. I agree with Philip and Sue. I think adding "from" unnecessarily inflates the user story and fosters redundancy... considering your user stories should be referring to the features/functionality of the system that's being developed.

  4. This comment has been removed by the author.

  5. Ditto on not including solution design criteria.
    Also - I have found that forcing the "I want" to refer to a user task, while an admirable goal to reach for, is too restrictive as a blanket format, especially as we want User Stories to be in the stakeholders' language. The thing that "I want" as a user, is not always to do a task. E.g., 'As Marketing VP, I want Rewards Points to appear on all communications with Customers so that our loyalty program will be given greater visibility and impact customer decisions...'. This expresses a requirement but it does not relate to a specific task (though it has an impact on many existing tasks). I like to write the Story as described above, and trace it to Use Cases to clarify which tasks the requirement needs to be added to.

  6. Thank you all for the comments. Because this is meant to be a starter kit, I find that while I typically start with a very simple form of the user story statement (canonical form), the more tightly the team works with the PO, the more likely there is an open discussion on business needs and technical solutions. I do emphasize the discussion because this is ultimately where I think the key to requirements is (i.e., its not so much about how its written but the discussion that ensues). Feel free to check out my new article that expresses this perspective at: