Rolling Wave User Stories: How to Handle Specifications

there are two extreme views on requirements documentation (most use user stories to describe requirements these days):

1. user story is just an invitation to communication. it should be very short.
2. we should document requirements fully, with all known details.

most likely, you accept option 1 and reject option 2. if you ask me what option i prefer, i will answer “both.” hold on to your tomatoes and read on.

let’s say, you start a project and have a backlog with 100 user stories. this is the stage where you should keep user stories descriptions short. don’t waste time, many of these stories will never make it into production, they will die.

you pick a user story and ready to start development. at this moment you have a solution and this solution should be documented. short description is not enough, since some details may be lost and implemented incorrectly, this will lead to re-work and time waste. at this stage you shouldn’t worry that detailed description of a user story is a waste, this story is going to development phase anyway.

simply speaking, each user story has a life-cycle: birth → solution → implementation → release . let’s review it:

birth
someone has an idea and user story is added into a backlog. just a short description is fine in this case.

solution
there are various methods to create a solution for the problem that user story describes. maybe you have a special ux phase and special ux teams that brainstorm possible solutions. maybe you discuss and invent solution in development team just before implementation. maybe product owner creates a solution alone ( worst case ). still somehow you have a solution.

then you should document the solution with quite many details to make sure that solution will not be misinterpreted. here you will argue that live communication is better than specification. i agree and will follow on below, but if you have a gap between solution and implementation phases (which is often the case), you have a good chance to forget many things about the solution. you will end up with sub-cycle: forget → remember → lost some details → re-work. this sub-cycle generates nothing but waste.

implementation
implementation may take several hours, or may take several weeks (happens). if a solution was invented outside a development team, it’s extremely important to have a kick-start meeting, discuss the solution again and find all weaknesses in it . it may happen that solution is unideal and can be improved. kick-start meeting brings everyone on the same page and every team member understands how it should work.

right after the kick-start meeting user story should have as much details as possible, including positive and negative flows, texts and labels, final design, etc. memory is a good thing, but it fails quite often. don’t rely on your own memory and on memory of other people, put everything you know into text and images .

release
when user story is done, there is not much value in documentation. if there are some minor discrepancies — that is not a problem. sure, it can be used as a reference for technical writer, for example, so, depending on your context, you may want to have it corrected.

the main idea is that importance of documentation is low initially, highest in the implementation phase and falls down again after the release. full documentation just in time is a good practice .

you may worry that it sounds heavy, but in real life a user story can pass all these phases in a single day. for such quick stories full documentation looks like an overhead, but usually it’s very short as well and may take 10 minutes to write.

i personally like when user story is fully documented ( at the right time! ) with all important cases, has final design attached, has all labels nailed and provides a good vision about the solution .

with many user stories you have rolling waves. like that:

now fish out your tomatoes and throw as many as you want.