dan sandler

Writing an effective user story

     The genesis of the article came out of the ad industry after seeing years of horrifically poor Service Work Orders (SWOs) for ad campaigns. When Agile became really popular and drifted into that industry(my industry at the time) the quality of the SWOs didn't improve. The concept of a more formal development structure and iterative work was easy to grasp but writing skills lacked. While my focus here is geared more towards Agile, the guideline would only help non-Agile environments. Keep in mind, I don't hold anything in the article as has to be done "by the book" since situations usually dictate the method of how the work will be done.

To start, my definition of a user story is a method of transmitting work into a development stream. This page will provide you with an outline for writing user stories from which you'll be able to develop your own style. Commonly a user story is developed around four major sections; description, acceptance criteria, requirements, & test criteria. While all of these sections are not mandatory, it is highly advisable that they be included whenever possible so work can be easily transferable across team members.



     Description as clearly as possible the goal of this work. This is a dialog in layman's terms what work is to be done and could include background information. What is gained functionally? What are the produced results? Who/whom will it benefit? This will roughly reflect what is targeted in the acceptance criteria. 


Examples of common starts to this section could be....

  • As a consumer I need to be able to make purchases with a credit card....
  • As a supervisor I need to be able to review...
  • Content editors need to be able to edit content from within...

Please keep in mind that the example text does not need to start with "As a ____" but it can help as a writing mechanism to setup who the audience is and what is the target goal

Acceptance Criteria

This is a more technically based area where specific instructions are provided. This can be high level instruction but focus' on clear technical direction on the work to be completed.



List any known prerequisites, requirement values or dependencies needed to complete the work as identified in the acceptance criteria.


Test Criteria

To ensure the work was completed properly, the test criteria outlines what needs to be tested. When those tests are completed satisfactorily the story owner can then accept the story as completed for the sprint. The information here is shared at minimum by two departments but other department may focus on this as a means of guaranteeing a release. Both the development & QA teams will use the information contained here; development uses the information to test and to know when work is completed while QA will use it to test & confirm that the work was completed properly.



Example Story

As a consumer of widgets, I require widgets to be in multiple colors but primarily blue. Please create blue widgets.


Acceptance Criteria:

Create blue widgets that are in a shade of blue no darker or lighter than the color specified.



Blue widget color RGB & CMYK values:

  • RGB
    • R 51
    • G 153
    • B 204
  • CMYK
    • C 73
    • M 26
    • Y 5
    • K 0


Test Requirements:

Please ensure that the color widget produced matches the color defined as either CMYK or RGB.