Academy

Writing user stories that developers actually like.

A practical guide to stories and acceptance criteria that cut down the back-and-forth.

A user story is a promise of a conversation, not a full specification. But a good story makes that conversation short and useful. Here's what we teach.

The basic shape

As a [type of user], I want [something], so that [reason]. The "so that" is the most important part. It tells the team what problem they're solving, which lets them suggest a better solution.

Make it small

A story should be finishable in a few days. If it can't be, split it, usually by user type, by step in the process, or by happy path first and exceptions later.

Write acceptance criteria people can test

Use concrete examples. "Given a parent with two children, when one child completes a task, then that child's points increase and the other child's don't." A tester can check that. "Points should work correctly" can't be tested.

Cover the unhappy paths

What happens when the payment fails, the field is empty, or the user doesn't have permission? Developers will ask, so answer it in the story.

Leave out the how

Describe the outcome, not the button colour or database table, unless it truly matters. Let the team design the solution.

A quick checklist before you hand it over

  • Is the user and the reason clear?
  • Could it be built and tested in a few days?
  • Do the acceptance criteria include at least one unhappy path?
  • Would a developer need a meeting to start? If yes, add what they'd ask.

Practise this with real case work at TemTed Academy.

Keep reading

More from TemTed.