Blue Flower

A popular template for user stories is

As a <persona>, I want <some goal> so that <some reason>

For example,

As a blogger, I want the blog system to return a permalink to my posts so that I can give a stable link to people who want to refer to them.

This is variously known as the canonical form, the role-feature-reason form, or the Contextra from. (It was popularized by Rachael Davies when she was at Contextra.)

The format is widely recommended. Mike Cohn lists some of its advantages here.

Recently, I have been seeing a lot of what I would call fake canonical stories. Here are some real-life examples, slightly edited to protect the authors:

  1. As a DBA, the <product> should generate a report of all database changes.
  2. As a <product> user I want to make the <feature> process easier for users.
  3. As a user of <product>, when a problem is encountered with the <feature>, the <option> should enable the <product> to facilitate the request by 'failing over' to use <other product>.

The first story implies that the DBA and the product are one and the same. The second implies that the users, not the developers, are the ones enhancing the product. And the third one is just ungrammatical and difficult to parse.

The authors of these stories realized that they were supposed to put "As a" on the front of their stories, but they didn't really understand why, so they were just going through the motions.

Why do we write stories in canonical form? It is not because some Scrum book, or Scrum Master, or Agile Coach decreed that all stories must start with "As a". No, there are sound reasons why we do this.

The first is that it makes clear the viewpoint of the person who is requesting the story. Consider these hypothetical stories about a password mechanism:

  1. As a Security Officer, I want passwords that are hard to guess, so people don't break into my system.
  2. As a User, I want passwords that I can remember, so I have half a chance of being able to log in.
  3. As a Hacker, I want easy-to-guess passwords, so it is easy to hack the system.

The third story wouldn't actually be in your backlog, of course, but my point is that the knowing the persona that wants the enhancement helps a lot in understanding it.

Some teams go as far as defining personas that typify what they think their customer roles are like, for example, "Terri is a 59-year-old database administrator who is much more comfortable with green-screen terminals than with the web." But that is a topic for another post, especially since there is some controversy about coming up with stereotypes about one's customers.

The second item in the canonical form is what the story is asking for.

The third item in the canonical form is why? This helps clear up ambiguities in the what.

Let's look at the first story, slightly edited to be more grammatically correct:

As a DBA, I want the <product> to generate a report of all database changes.

Should this report contain:

  • Just the number of changes, so the DBA can know the level of activity for each database?
  • The time, date, and user ID of each change, so the DBA can watch for suspicious activity?
  • Before and after images of each changed field, so the DBA can see how the data is being changed?

We don't really know. But if we rewrite the story with a why clause, it is much easier to know:

As a DBA, I want <product> to generate a report of a database changes, so I can see who is modifying the database.

One could argue that this could be dealt with in the what clause:

As a DBA, I want <product> to generate a report listing the time and date of each change to a database, as well as the name of the database and the user who made the change.

But this is getting into the details too early in the design process. Initially, a story is a conversation starter. Given the who, what, and why of the story, the Product Owner and the team can develop the story further and come up with the details that will go into the acceptance criteria.

Do stories always have to be written in canonical form? I have yet to see a story that couldn't be written that way, so that is generally how I write my stories. But with some stories, it isn't really essential. For example, on a new project, you might have a story like this:

We need to set up a Git server to be our source code repository.

or like this:

As a developer, I would like to have a Git source-code repository so I can commit changes and roll them back as necessary.

Does the second story impart more information than the first? Not really. We know why we need a source code repository, and the reasons are actually too many to express in a one-sentence story.

But this is an infrastructure story. In a feature (customer-value) story, it is much more likely that you will need the canonical form to provide the information needed to properly start designing the story.

Depending on the story, you may or may not need canonical form. But if you use it, please use it, rather than just slapping "As a" on the front. I think you will find that using the canonical form helps stories be the good conversation starters that we would like them to be.