Create Good User Stories

A good user story (aka feature briefing) is small, precise, unambiguous, and makes developers happy.

One of the main responsibilities of a product owner is to write user stories. The web is chock-full of sites, videos, and books with examples of how to write good user stories, so I won’t repeat all that wisdom here.

Generally speaking though a good user story:

• Addresses a single feature or bug.
• Describes a feature which can be developed in less than a week, but preferably in just a few days (bug fixes are exceptions: very small fixes may even take less than an hour).
• Leaves no room for guessing or misinterpretation by the developer.

Besides the textual description of a user story, a good user story must be accompanied by:

• Mockups for all relevant states (empty, loading, partial, error, ideal states). See also this article and this article.
• UI design assets (HTML, CSS, images, et cetera) which are ready-to-use by the developer.
  • The design assets must cover all relevant states.
  • The design assets must be responsive.
  • Images must be cropped and scaled. Don’t expect developers to do this for you.
• A description which user metrics need to be measured using e.g. Mixpanel or similar event tracking service.
• A description of the typical, intended user type (persona) which is going to use the feature (regular user, administrator, etc).
• A description of the necessary database schema changes.
  • If possible, the schema changes should precede this user story (in a separate PR) in order to reduce the complexity of this user story.
  • If the schema change must happen at exactly the same time as the feature deploy, then a (scripted) migration must be part of the final PR.

An optional screen recording in which the product owner explains the mockups and intended end result. This is especially handy if you work with remote developers or if the product owner is very busy and only has time to explain a user story once. Developers can watch such screen recordings again as often as they like.