This example shows one way of working with Concordion. Given the flexibility that is built into Concordion, you can use it in many ways. For example, you might be documenting your features, rather than individual stories. Or you might not be working with stories or features at all. You might be writing your specifications after coding. But you'll get more benefit from discussing them before.

Example: Online Shopping Site

Imagine that we are working on an online shopping site, like Amazon. We are already several iterations in, but there's still plenty of functionality we can add.

1. Choose a story to be implemented

From the dozens of possible stories, the following card has been chosen for implementation in this iteration:

Story card

On the back of the card are some rough jottings about the scope:

Story card - rough scope

2. Write a story page

The story page acts as a summary of the acceptance criteria as agreed by the group. It is the output of a discussion about the story between developers, testers and the story owner / business expert.

In our case, the page is divided into sections "Automated", "Manual" and "Out of Scope". Many of the repetitive checks can often be automated, but manual checks are sometimes needed as well. For example, one of the manual tests is to "check user-interface changes are consistent with rest of system"; this kind of test cannot be easily automated. By automating the checks, we free up time for our testers to perform exploratory testing, using their experience and creativity to explore new test ideas.

Story page

3. Write acceptance criteria and examples

Again, these are discussed as a group. This allows us to clarify requirements, resolve misunderstandings and find requirements defects and gaps. It also gets the team on the same page, developing a shared understanding and a common language. By doing this before any coding begins, we increase our chances of building the right thing, minimising the amount of rework needed.

Each of the items under the "Automated" heading in the story page is a link to an acceptance test. These tests are under a different hierarchy to the stories and organised in a way that results in easily navigable documentation. If you use the right conventions, Concordion will automatically insert breadcrumbs for you.

Each page consists of a concise heading, a description and one or more examples. The breadcrumbs give you context, so you don't need to have long wordy headings and descriptions.

You'll notice that this page is pretty simple to understand and maybe looks overly simplistic. But it's not; rather than having complicated tests that test many things, you can have simple tests that test one thing at a time. Complex behaviours are defined one small strand at a time by decomposing the behaviour. The "Further Details" section at the bottom of the page lists a number of questions that you might ask about the functionality. Each question links to another (equally simple) specification and so on until you run out of questions.

Acceptance test

4. Now everyone knows what "done" means for the story

It takes some time to write the acceptance criteria; perhaps 2 or 3 hours for a 5 pair-day story. But it pays dividends in terms of focus, test coverage, and cutting scope creep. Plus, if you take care, you can build up some very valuable documentation that does not go stale.