Just a Simple Paragraph

This post is the fourth one in the first Build-Measure-Learn cycle. In the last post, I broke down the story “Import a Text or Document File” into smaller stories. From the resulting set of smaller stories, I have picked the one called “Import a File with a Single Paragraph”. I am going to detail this story and add some acceptance criteria.

A Smaller User Story

In the first assessment for the six characteristics INVEST of a good user story the size of the story “Import a text or document file” gave some ground for criticism. Therefore, the story was broken down into smaller stories. I am going to pick the simplest one “Import a file with a single paragraph”. This is the current draft of it with persona Anton in mind:

As Anton,
I want to import a file with a single paragraph
so that the text is available for further analysis

The story addresses files, which contains just a single paragraph. Now the story is small enough so it eases the estimate and testing. The other characteristics independent, negotiable and valuable were already assessed and confirmed.

Card, Conversation, Confirmation

According to the characteristics of INVEST the story is ready. However, in the last post I missed an important thing related to User Stories, the three aspects of Card, Conversation and Conformation (see [JeffriesCCC]).

A story is written on a card. However, it is just some kind of reference catching the most important data for the requirement. The card is primarily used in planning and for conversation on the details.

During the conversation, the project stakeholders deeply discuss the details of the requirement. Conversation happens during the estimation process and the planning phase. A conversation can be supplemented with documents and examples. The examples are useful for the confirmation of a user story.

The confirmation tells the stakeholders that the story has been successfully implemented. It is always the customer who confirms the success of the user story. In addition, the customer typically defines acceptance criteria, which contains concrete examples. The set of acceptance criteria defines the acceptance test the story has to pass.

Acceptance Criteria

The story “Import a file with a single paragraph” described above looks fine so far. The next step is to talk about the details and write them down as acceptance criteria down. This is done in accordance with the characteristics of negotiable and testable stories.

Because the story requires a file import it is clear that the system has to offer the possibility to import a file. This leads me to the following acceptance criteria:

Given Anton has access to the system
when he opens the import dialog
then there is an opportunity for a file upload

The above acceptance criterion describes how the user interacts with the system. The user interface should have an import dialog for file upload. This criterion defines a check for a user interface element.

Another part of the story states that the text of an imported file is available in the system. This leads me to:

Given Anton has selected a text file with a single paragraph
when he starts the import of the selected file
then the system imports the file and the text is in the system available

The second criterion focusses on a system function; it describes what should happen when a file is imported. The criterion defines a check on the system’s logic layer.

What is next?

In the next blog post, I will deal with Acceptance Test Driven Development. The acceptance criteria above will serve as the specification by example.


[Cohn2004] Mike Cohn, User Stories Applied: For Agile Software Development
(1st edition, Addison-Wesley 2004).

Ron Jeffries; ‘Essential XP: Card, Conversation, Confirmation’, <http://ronjeffries.com/xprog/articles/expcardconversationconfirmation/> accessed on May 26th, 2017.

Leave a Reply