Get to the Forefront of
Agile Innovation

As part of our commitment to excellence and innovation, we’re inviting you to join our exclusive 365-day free beta program. This is a unique opportunity to experience firsthand the transformative impact scagile can have on your agile project management processes, at no cost.

In the beginning is the word – In Scrum is the User Story

Software developers do not like writing texts. This is one of the most universal facts since the invention of software development. By the way, they also don’t like to read text, at least not when it comes to technical documentation or specifications that are important or relevant to their project.

The latter is not surprising, since these texts were written by developers or people close to them, who, as mentioned above, do not like writing texts at all. This, of course, has a direct effect on the quality said texts.

It’ s a vicious cycle. You might think that Scrum was either invented by these frustrated developers, or by project managers who had sympathy for developers, or who simply gave up on demanding documentation without any realistic prospect of ever getting it in an appropriate quality.

In line with this is the ‘working software over comprehensive documentation’ principle from the ‘Manifesto For Agile Software Development’, which in my professional practice is probably the phrase most often quoted by software developers.

Even though the above-mentioned parties are right in a way, unfortunately the mentality too often affects how Stories are written. And that has fatal consequences.

Badly written, but above all incomplete User Stories are one of the most frequent reasons for the failure of Scrum projects.

This is partly due to a misinterpretation of yet another principle from the Manifesto: ‘Individuals and interactions over processes and tools’ or ‘The most efficient and effective method of conveying information to and within a development team is face-to-face conversation’. At first glance, both do not sound like good arguments for a plea in favor of well-written Stories.

However, and as we will see later, a well-written User Story doesn’t necessarily have to be very long; and secondly, the two principles mentioned above are based on well-written Stories and describe what the process should look like afterwards.

And there is still a lot to clarify, starting with architectural decisions about implementation plan, CI strategy, test plan, deployment strategy, know-how transfer, and so on. These are all matters in which direct communication between the parties involved is essential and reveals significant advantages of the Scrum method.

The User Story, as a written artefact, forms the basis and the reliable point of reference for this form of communication and therefore demands special attention.

Again, almost all processes and decisions that take place in a Scrum project relate to the underlying Stories, because it doesn’t take much more to develop good software.

We have now heard enough about the importance of a User Story in the Scrum process. Now we’ll deal with the big question: How should a good Story be written?

Here we go… 

Well, not yet. A User Story is part of a Product Backlog that maps all the functional requirements relevant to the software project. In large development projects, it is advisable to introduce a two-tier hierarchy with epics and Stories.

Generally speaking, epics represent entire software modules or, from a functional perspective, higher-level business process groups (e.g. ordering, accounting, CRM or warehousing within an ERP system), while User Stories represent the individual functional requirements.

In smaller projects, such as a web shop, the epic level can be omitted. But you can never do without Stories.

I’ll discuss here how a good Story should be written. The same is essentially true for epics, and everything we say about the Story can be easily transferred to epics, with the weighting varying slightly.

A USer Story is usually written by the Product Owner (PO), but at the very minimum he is solely responsible for the Story and it cannot be delegated. The PO may, of course, use any help he can think of when writing the Story. Before a PO starts writing a Story, he should consider one or more of the following points:

1) A User Story should be written from a purely functional perspective. Only the ‘what’ is described, not the ‘how’. The ‘how’ will later be the responsibility of the development team in all of the follow-up processes mentioned above, for which face-to-face communication becomes so important.

2) The User Story should later be read and understood by people (developers) and – very important – in an ideal case, there should be nothing more to text than the Story. The Story must therefore describe the functional requirement completely and in a way that is appropriate for the target group. The target group are the developers of the Dev Team, and not stakeholders of the organization.

3) At the time of reading (Sprint Planning), usually not all the Stories for the overall project will be available, so the User Story must somehow manage to show the vision of the overall product so that important architectural decisions can be made at this early stage.

4) The developers already have a hard time anyway; they only get the software described slice by slice and ideally are supposed to deliver functional software in every Sprint. The Stories must support this process and not prevent it. They’re not just requirements, they’re part of the whole process, and the Story must include the PO’s effort to support that process. This may sound a bit vague, but most Stories don’t show this at all. Read Kant’s Critique of Pure Reason. The subject matter is not trivial, but in every line you can find Mr Kant’s tireless efforts to really take the reader by the hand and make it understandable. This is a trait that Mr. Hegel has not really made his own. In his case, the world is being described from above (albeit no less witty at its core).

5) The first milestone in the processing of a User Story in Sprint Planning II is a commitment in the form of a valid estimate. The Story must therefore be assessable. It would also be useful to open up the possibility of measuring the velocity of the team at a later date. In this way, it actually becomes part of the whole process and does not simply represent the functional requirement. To achieve this, each Story should represent one – and only one – functional elementary process. This is characterized by the following properties:

a) An elementary process is a self-contained business process and should not be further divisible (e.g. the change of address in an ordering process, the check-in on an airline website).

b) The elementary process should be functionally testable end-2-end.

The description of such elementary processes in the Stories gives you the opportunity to easily apply any metric such as Story Points, Function Points or time to the estimation and will massively support the entire Scrum process. You should not do without these advantages.

A good User Story: What it looks like

A Story should consist of at least four content components, which I will describe briefly below:

1. Motivation:

Motivation describes why this User Story is needed at all, what value the feature described in it has for the product from the point of view of the Product Owner (PO), but also what significance this Story has in the development process (e.g. the first proof of concept for a module or the final Story, which means the completion of the project).

Since each Story in the product backlog is unique and the PO should provide the developers with both a vision of the product and development guidelines, motivation is the best place to do just that.

Understanding the vision of the product is incredibly important for developers when it comes to making far-sighted architectural decisions, even though not all Stories are available in the early stages of development.

In my experience, a detailed description of the motivation is even more important than the description of the feature itself. Usually I use more text for this, because I as a PO can check my own intention very well and put it up for discussion in Sprint Planning.

If you are clear about the motives of your actions, you can plan your actions very well.

This is exactly the case when writing a Story. If I have clearly stated my motivation, the description of the subject is usually much easier and, above all, more consistent.

2. Description:

The motivation is followed by the description, already mentioned above, which describes the object of what is to be developed, i.e. the scope.

The ‘why’ (motivation) is followed by the ‘what’ (description).

I often get asked how a perfect description should look like, how much text, which style, etc. There is no obvious answer to this question for the following reason:

In my article on “The Essence of Scrum”, I identified ‘communication’ as one of the four basic principles of Scrum. This manifests itself in a special way in the description of the User Stories.

First and foremost, the way a User Story is described expresses the state of communication between the team and the PO. And this can change drastically over the course of a project, or at least it should.

A new, young, inexperienced team at the beginning of a project certainly needs a lot of detailed descriptions in a User Story. A team that has already perfectly adapted the project vision, knows the thoughts of the PO very well and is very deep in the subject matter does not. A few simple sketches and a few explanatory comments during the planning or refinement are usually enough for the latter.

Precisely because the communication will change after a few Sprints and well executed retrospectives, it doesn’t make sense – and is even counterproductive – to have all the Stories written before the project starts.

Better plan 1 to a maximum of 3 Sprints in advance, depending on the length of the Sprint.

In the description of a Story everything should be allowed and almost nothing  is forbidden.

It doesn’t matter if you use a UML diagram or write full text, create a mockup or use links to the competition – it’s entirely up to you. The only caveat: it must remain functional in the way mentioned above.

Basically I recommend the following consideration: IT in general consists of three things: data, processes and interfaces. If you specify in the description which data is processed with what processes via which interfaces, then you won’t be completely wrong.

3. Acceptance Criteria:

After the description we have the acceptance criteria, which list when it is good, what has been developed and under which circumstances the implementation of the User Story is accepted.

The most common mistake made here by less experienced POs is to say that the acceptance criteria is that everything that has been implemented is working, in other words, repeating the description.

That’s simple and very obvious, but it’s not goal-oriented, because that’s what the developers could have imagined.

POs do this quite often, because it’s not all that easy to write good Acceptance Criteria. This is why I would like to make two recommendations:

The first is: Force yourself to write at least 3 to 5 Acceptance Criteria for each Story. Above all, don’t forget the ‘Non-Functional-Requirements’ (NFR), i.e. that the function runs on a certain environment with expected response times, or that an average test user can intuitively operate the application, etc. The NFR’s are of course much better defined in the Definition of Done, because they are not only valid for one User Story, but for the whole application.

My second recommendation has something to do with the fourth and following section, so I’ll explain it right below.

4. Test Cases:

Test cases are used to answer the question of how the Acceptance Criteria are verified. From motivation through description and Acceptance Criteria to the test cases, this reads like this: 

Scrum User Story

  1. Why do I want this feature (Motivation)?
  2. What should be implemented (Description)?
  3. When will the implementation be successful (Acceptance Criteria)?
  4. How do I check that (Test Cases)?

These are the four components in a logical sequence.

My second recommendation for writing Acceptance Criteria above is this:

Think about how you would test the feature and what you would expect as a result of the tests.

And then create a correlation between the test cases and the Acceptance Criteria. When creating the test cases, make sure that not only the good-case is tested, but also all kinds of deviating behavior of the application or the users. While the motivation describes the PO’s perspective and the description the user’s perspective, the Acceptance Criteria and the test cases introduce a third and very important perspective, namely the perspective of the application itself.

Would you like some more? Test-driven Development

To close this article off nicely, now I’d like to give you a suggestion or a trick that you should at least think about. Above I have described the four components of a User Story as a logical order.

If you really want to do the project, your developers, the performance and the quality a favor, change the order and go from bottom to top after writing the motivation.

In other words, you describe the test cases immediately after the motivation. Technically, you can then even skip the description and the Acceptance Criteria, or at least shorten them considerably.

This is called ‘test-driven development’, the supreme discipline of software development, because it enables rapid and precise development. Particularly in SAFe and the ScrumXP cited there, this method is emphasized and corresponds to one of the basic principles of Build-in-Quality.

If a developer already knows the test cases against which he is supposed to develop and can assume that these are also comprehensive, there are usually no questions left unanswered and they get very good results at the end of the Sprint.

However, this test-driven development is so rare in practical reality as is red mercury, just like a myth. This is usually because POs shy away from writing test cases like the devil shies away from holy water.

In fact, writing many test cases continuously, but most importantly at an early stage, is no trivial matter. It takes practice, it exposes all conceptual weaknesses or information gaps the PO may have, it requires a very precise knowledge of the business process to be implemented and one has to be extremely disciplined.

It’s not technically difficult in itself, but it’s a lot of trouble and I haven’t seen many POs who have made such a commitment to a project that they took it upon themselves with ‘patriotic’ joy.

Please convince me of the opposite!