Agile Documentation – Is It a Good Idea to Write Requirements by Stories?

agiledocumentationRequirementsuser-story

We're using agile methods in my current project at the moment, and we have heaps of stories like these:

  • As an assistant, I want to pay a customer a refund so that they can
    get some money when they request it

  • As a customer, I want to pay for a purchase so that I can receive my
    item.

How we've done it so far is to pick the most important stories every sprint and elaborate it into a number of formal requirements specs (we group some of the stories that are similar together in the same spec). Depending on the story, it could just be a button on a screen or an entire workflow.

The problem now is that because there's so many stories, it's not immediately clear, for any part of the system which stories relate to it.

It works at the time of developers, every sprint the devs just get a spec outlining what they need to do and the changes they need to make. But in terms of maintaining this story list and for testing, its starting to get really hard tracking bugs and in general just maintaining the specs, because one piece of functionality in the screen might have been documented in a number of different places due to it being split by story.

Is writing specs based on stories a good idea? Have we written the stories in the wrong way?

Best Answer

This might be controversial but here it goes!

We have worked on a real time systems where one of the past bosses of mine suggested that let's do AGILE! It was easy to win management on that really; however, it was easier said than done.

The concept of stories is good - but to be very upfront, it is quite vague. What is a story, really? The real issue is that using stories alone (and much the same holds for Use cases as well) have several issues - as follows:

  1. Requirements cannot be out of context (unless you are making gross repetitions so many times). There are assumptions, background knowledge and other requirements which are linked too a given requirement; they make sense only under a context and only under a specific order. Implementing most important one first makes business sense but when you file them at least - keep a complete referencing right from the beginning when yo collect them. Requirement word itself is complex and is not really limited to Use-Case / Stories. Indeed stories are actionable, but then there are requirements that may not be actionable, such as performance, constraints to be met, business rules etc.

  2. Requirements needs to be appropriate in size and in quantifiable manner else you can never have a need for more than 1 large story! What forms exactly 1 story?

    • is it one full detailed scenario? (e.g. one story when ATM rejects a transaction)
    • is it one set of action that user performs? (e.g. full story about withdrawal)
    • or is it one screen in the user interface? (e.g. withdrawal screen as a full story).
    • How do really quantify very crisp business rules with stories? Honestly, it can be any of the above. The point is how much confined and granular you go is quite a personal style. If it works -it is fine;

  3. Domain knowledge is really requirement! A simple example, of an Architect who knows various properties of Glass, Steel and Wood. this knowledge is not part of the requirement document for the building per say! Same way, if you are writing a banking software - there are whole bunch of concepts about banking. Stating them, as Requirement itself makes it non-tractable because it doesn't tell you what should software do as opposed to how the world works. Does story includes such domain intricacies? or does it exclude this?

  4. Modeling the world is prerequisite not quite supported by.
    There has been a lot of literature on Modeling which focuses on just understanding how the world works is a background knowledge. Modeling forms firm foundation on which requirements gain clear meaning; however such a thing should be upfront. Unfortunately, most of the agile practices refuses value in upfront modeling in the interest of quicker and leaner deliveries; but that i still think is a major show stopper when things has to scale. Many project do succeed not because modeling is irrelevant - but seasoned engineers know them in their head and doesn't need much explicit guidance.

So coming to your question:

Is writing specs based on stories a good idea? Have we written the stories in the wrong way?

I think user stories does have value as explicit verdict given by customer. But if they are poorly organized and insufficiently detailed (or vague) there is a problem. Unless you have a larger structure to accumulate the broader understanding (domain knowledge) and scope (total spec). User stories only for segments or elements within larger such system.

PS: I have exact opinion about Use cases (as they are depicted in oval diagrams) that unless you put them in appropriate context and at appropriate granularity they don't do any good job. (I call them useless cases). The only credible source i find to make Use case writing truly scalable and meaningful is Writing effective Use cases by Cockburn

Related Topic