How to write user stories and defects efficiently

In product management everything goes back to stories. No matter how grand your idea is or how complex the new initiative might seem in the end they all have to be sliced into easy to digest stories – the most basic work item. In this post I will not cover how to slice stories, nor the effort required to complete a story but how we should structure our stories in order to be easily understood by a wide variety of stakeholders, from developers to fellow product managers to business stakeholders.

In order to make everything as easy to understand as possible I always divide stories by type: Commercial stories, Technical stories, Investigations, Defects and Technical Tasks (not covered in this article). They are an integral part of every development process (agile or waterfall) and although most commonly used as a handover document between product and development they are also used as a reference document for non technical stakeholders on how a feature is intended to function. Since they have to provide clarity the details the contain have to be specific to each work item type and have to be written as clearly as possible.

Commercial stories are work items that generally drive the product forward by enhancing it’s existing functionalities or implementing new ones. This features are user facing, meaning that usually end users will get to see their direct value and will have a high impact. Writing them usually falls under the product manager/owner or the business analyst and the details they contain are less technical in nature. The minimum set of items they should contain is:

• Main story written in the agile format: As a <persona> I want to <action> so that <outcome>.
• Acceptance criteria using the the BDD format: Given | When | Then
• Designs (user flows, front-end designs)
• Additional information (info on how the story originated, story background, notes from stakeholders)
• Cross team impact
• Require DBA review (yes/no)
• KPIs
• Estimate (Time, Story Points, T-Shirt size, etc. )
• Rank / Score (RICE, Impact vs Effort, etc.)

Technical stories are work items that enhance the technical functionality of the product, solves technical constraints or updates the code to newer libraries (e.g. enhances product speed, reduce deployment time, create new API endpoint to be used internally, etc. ). Although customers can see the result of these features (e.g. page load time decreasing), most often they go unnoticed. Since these usually require an in dept technical understanding of the product they are written by members of the development team together with the Product Managers. In order to be easily understood they have to at least contain:

• Main story written in the agile format: As a <persona> I want to <action> so that <outcome>.
• Acceptance criteria using the the BDD format: Given | When | Then
• What we want to achieve with the enhancement vs. where we are now
• Additional relevant information
• Cross team impact
• Require DBA review (yes/no)
• KPI
• Estimate (Time, Story Points, T-Shirt size, etc. )
• Rank / Score (RICE, Impact vs Effort, etc.)

Investigations are work items that give developers a chance to prototype a new piece of functionality or test different ways of implementing new features in order to find the best one. This feature can be both commercial or technical however their outcome is not production code but a set of conclusions which will serve as the base for new commercial or technical features. These can be written by Product Managers, Business Analysts or members of the development team depending on their object. In order to be efficient they have to contain at least:

• Explanation of what we need to investigate
• Explanation of why we need to do the investigation
• The desired outcome (what we hope to achieve / prove / verify)
• Timebox (this items don’t usually have estimates but are timeboxed)
• Actual outcome of the investigation (filled in after the investigation is complete)

Defects are work items which can be split in 2 categories sprint defects and production defects. The first category are items identified by the development team during the development process and are usually closed before a sprint ends – hence their names. Production defects are items identified by internal teams or external customers after a feature was pushed to production. Both items the same information however the sprint defects are generally raised by QA or developers while production defects by QA or Customer Success or support team members on behalf of customers. The items each card contains are:

• Description
• Reproduction steps (the higher the detail the better)
• Current outcome
• Desired outcome
• Reach (how many customers it impacts) – (one / multiple / all)
• Impact (how critical the defect is)
• Priority (Critical / High / Medium / Low)
• Reproducible (how easy can be reproduced)
• Specific customer impacted (especially relevant if only a handful / single customer impacted)

Any organisation that hopes to delivery quality software has to write quality stories since these are the foundation of the source code. They provide clarity to stakeholders, mitigate possible conflicts and guide developers on expectations.

This post has been published on www.productschool.com communities.