Is it a good idea to write requirements specifications by stories?

Question

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?

Answer 1

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

Answer 2

> Writing specs by stories? a good idea?

Yes if you can manage interdependencies and priorities of your stories.

Here is an article about story maps that can help you to order and mange many userstories.

Answer 3

As of time writing this answer, I've realized it's not about testing, it's about documentation. You should first read agile manifesto:

[We value] working software over comprehensive documentation

So, you should make your specifications executable, i.e. write them as a fully automated set of tests.

Is writing specs based on stories a good idea?

Yes, imho, it is. It's called "behaviour driven development" or "specification by example". In ruby there's a great tool cucumber that helps in that much .

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.

Why do you want it to be clear? I mean, do you really need a "test/code" traceability matrix? The advantage of writing tests as a specification is that you don't need a separate "requirements/tests" traceability, because tests become requirements. For the purposes of integration testing you should treat your software as a whole, not as separate parts.

You might need a coverage tool to see if there are "dead" modules, parts of your system not covered by your specification tests. But you really shouldn't care what specification this particular code corresponds to. It should be vice versa: from a particular specification you should know which part of the system corresponds to it. You shouldn't worry about some duplication in your specifications. And if you apply a DRY principle to your code there would be dozens of specs executing the same code.

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.

It's not that uncommon that hundreds of integration tests are broken by one little change in a critical module. That's where unit testing steps into.

You should structure your tests as such so that you can tell if a particular test covers a high level requirement, or just a subtle detail of it. If the latter, you should separate this test from your integration tests suite. The purpose of unit testing is to localize bugs. So that if you introduce a bug, there will be one and only one test failure.

Have we written the stories in the wrong way?

I think, you just need to organize your stories into epics either by user, e.g. "Customer", "Assistant", or by features/screens/workflows ("Purchase", "Refund").

And again, specification tests are not a replacement to unit testing. Read more

Answer 4

You mentioned a problem and the way how you solve it but you forget to mention some example of your specs and grouping and how it is related to the way how you develop your product.

Writing specs by stories? a good idea?

Agile doesn't forbid it. In agile you can do whatever you need to deliver maximal business value in sustainable pace. So if writing specs is something you need to deliver more business value it is absolutely OK to do that.

Your example shows two user stories. They are perhaps somehow related in your business logic but that is very common scenario.

If you need to bactrack functionality to user stories you can again use whatever suits you best including documentation, some diagrams or your "spec" but you must be prepared that maintaining these artifacts will cost you more as your complexity of the developed application increase. So the only question you must answer in this case is: If I don't use my specs will it cost us more? If the answer is yes you chose a better option.

The agile works best for small to medium projects with small team were whole architecture is held as tacit knowledge shared in the team. During iteration planning you will go through your picked stories, discuss an impact on the current implementation and write some tasks needed to complete the story. The real documentation in such case will be the test suite holding automatic acceptance and integration/unit tests. Once your SW or team grows the tacit knowledge will have to partially move to some documentation.

Answer 5

Now this is where abstraction plays a major role. You need to look at the stories wwith respect to the relevant perspective. Gather the nouns and verbs in the statements and confirm them. You cannot base your models upon personal assumptions.Also pay attention to detail.

Writing specs based upon user stories cannot be accurate. You need to dig extra detail and sometimes ignore detail which is not relevant. Specs should be written when your model is complete and accurate upon confirmation of your analyst.