Show all posts
4 years ago

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 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:

User Story flow phases

Someone has an idea and user story is added into a backlog. Just a short description is fine in this case.

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 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.

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.

User Story phases

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:

rolling waves user stories

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

  • indigo777

    no need to throw tomatoes, Michael. you sound too self-deprecating 🙂 your post looks simple, nice, and informative to me.

  • Eric Le Gallais

    Very interesting article! I’ll ask the P.O.s and analysts I coach to read it 🙂

  • Michael Dubakov

    @ericlegallais:disqus Thank you!

  • Giorgio

    I totally agree. Sometimes “agilists” positions are far too extreme on documentation. I only add a further distinction between customer-oriented business requirements definition, and solution-oriented requirements specification. The challenge is to keep documentation lean and focused.
    what: lean documentation of business requirements and corresponding solutions
    when: just in time, when it’s necessary (is BRD early needed as contract appendix, or not? Is end user documentation needed immediately, or not? and so on)
    how: simple and as visual as possible.
    I’m now examining Hemp (by David E.Jones) and TREDD (by Michael O’Reilly), but refining requirements definition strategy is an ongoing process that brings together the needs of outer stakeholders and inner team members.

  • Antonina Binetskaya

    Very good article! Thank you! Just in time.
    I’m going to discuss it with a team – possible it’ll help to take off some stress from BA.

  • Steven Gordon

    The key point is that this detailed documentation is waste:

    1. As you do state, after proper implementation and acceptance, the documentation has no use. Furthermore, subsequent stories may well change the final implementation of the system in a way that invalidates this documentation, but if it exists, you need to either keep it up to date or live with misinformation time bombs in your documentation.

    2. If the people in the “solution phase” include all implementors and testers and the implementation follows immediately, there is no time to forget. The solution phase should be done on a white board and digitally photographed. Sufficient documentation without any wasted time (and in a form that nobody will mistake months later as final).

    3. Many of the reasons for rework are because when the story that everybody collaborated faithfully on is exposed to the fuller population of users, misunderstandings about how the system will be actually used are exposed. This is inevitable for innovative software development. Putting extra up front work to avoid it only increases the cost of rework when it happens.

    Agile is about keeping the cost of change low and reducing the latency time between concept and implementation in order to get valuable feedback as soon as possible. Detailed documentation increases the cost of change and increases the latency time for customer feedback, thereby decreasing agility.

  • Jane

    I totally agree with the approach – however, not so much with the value of the documentation after implementation. I work in a BAU environment, and often have to go back to old documentation to work out what the “requirements” were – this is extremely difficult if they are not there! and yes, we could go back to the code, but often different developers come along who find it hard to make sense of what has been written! Therefore, I would argue that “there is much value in documentation” after implementation. No tomato’s by the way!

Get started
for free

Sync up your teams with a visual project management tool that adapts to your organization and gives you transparency across different projects and departments.
Visualize every step of the way.

By clicking Continue you agree to our Terms of service and Privacy policy