Having examined and analysed over 10,000 user stories from different sources we have built up some insight into what represents a good user story.  If you would like to learn to write better user stories, you should find this article useful.

What is a user story?

Before we start on the 10 steps, let us revisit the question of what is a user story.  A user story is typically described as a placeholder for a conversation about a user need.  Typically we refer to the three C’s:  Card, Conversation and Collaboration.  In many organisations however, the user stories ARE the list of requirements.

Agile purists and coaches will typically say that the user story should not be considered a substitute for written requirements, as this undermines the promotion of collaboration amongst team members.  However, in most cases in most organisations the list of user stories is the list of requirements.

And now, lets cover 10 steps to writing better user stories:

1. Focus on functional needs

Functionality should be written as follows, wherever possible:  As a __ I need to __  .  In each story, include all the functionality that makes it complete. Include data movements between systems (provided that your scope is to add, edit or delete such functionality).   A user story that begins with with “When” instead of “As a” is fine so long as it goes onto describe an functional event including a user, an object and an action.  e.g. “when the temperature sensor detects 100 degrees it sends a signal to disable the heat source”

TIP

Exclude team tasks and any configuration work that is not directly related to delivering new, changed or deleted functionality.

2. Clear and Unambiguous

If a user story is unclear, it WILL lead to bugs. This is absolutely crucial to resolve and resolve early.  It should be unambiguous to the intended readership (at least: users, developer, tester, analyst, designer).  The easy test for ambiguity is to ensure that any two readers of the same text reach the same understanding of what functionality needs to be provided – if in doubt, ask them.

TIP

Use data-related verbs such as update, send or save.  Avoid verbs such as: consider, provide, want, decide, support and assess . These are likely to mislead the reader.

3. Use rich user names

Avoid “as a user”.  Instead try to give context within your user names, for example: loggedin_customer, loggedin_marketing_agent.   loggedin_adminstrator.  This is informative about context without being wordy.

4. Concise

Overly verbose user stories that include too much detail of functional needs, design statements and test criteria will lead to confusion.  Keep your stories short, simple and precise.  It is better to be short and clear than to be over specified.

Try to keep your user stories small and simple yet sufficiently encompassing as to avoid story proliferation.  Two specific tips are to refer to objects not object types (too big) or object attributes ( too detailed).  For example “as a loggedin_customer I can update my profile” is better than “as a loggedin_customer I can update any data” or “as a loggedin_customer I can update my phone number”

5. Consistent

Be consistent with your user names and object names.

With data maintained within the system be consistent with the names you use, try to refer only to objects and object types as much as possible, avoid object attributes within stories. e.g. user_profile (that includes an attribute for date of birth) is better than date_of_birth.

6. Complete within itself

If a user story requires multiple functional steps, include them all. e.g.

Before: As a user I want to update the store details.

After: As a logged_in_administrator, I need to verify my permission [to update the store_record]. I can then update the store_record

The two functional statements indicate that persmissions need to be checked before an update can be performed.

7. CRUD Complete and unduplicated across a set

If we are updating store_information in the example above, is there also a similar user story that allows us to create a store?  Another story to  Delete a store?  And another story to display a store?  Missing stories are the cause of scope creep, which often cause projects to go on beyond their original schedule.

Similarly, beware duplicated user stories.   Duplicate requirements are less common, but they do occur, so check that you have not doubled up on functionality.

8. Testable

If a reader cannot readily understand how to test the user story, then it is not testable.   We are referring here to testing from a functional point of view.  Any constraints should be included, and any scalar constraints should be quantified.

9. Valuable and Traceable back to Business Outcomes

Although this is last on the list here, it is in many respects, the most important attribute of a user story.  If the story is not useful to the business then it should be excluded.  Ideally the value of the story can directly link to Capabilities and Outcomes that are measurable. i.e. there is clear linear traceability between the functionality of the user story to the capability that is needed to achieve the measurable business outcome.

10. Contains no design

User stories should not contain design statements.

Conclusion

These are 10 of my favourite tips for writing better user stories. I guarantee that if you follow these tips you will write better user stories, and that will lead to writing better software.

What if my user stories are not good?  Does it matter, so long as I have the gist of the story?  Yes it does.  Just one ambiguity will lead to wasted time and effort in interpretation, misinterpretation and some degree of rework.  One omission could require a major revisit of the design (or introduce technical debt if it is too late change the design).  So yes, great care is warranted when writing user stories or requirements.  Good requirements can lead to an on time delivery.  Poor requirements will certainly cost more and take longer.

Need More

Check out this excellent worked example of improving a user story.