Selected Poems and User Stories

A well-written user story is a masterpiece. It conveys motivation on behalf of the user. It articulates the criteria required to accept it. Yet, it’s sufficiently concise to comprehend at a glance. User stories are a form of poetry.

Well, let’s not get carried away. You don’t need to be Walt Whitman or Robert Frost to write a good user story. Instead, let’s aim for something with a bit more structure.

Much like a haiku with its 5–7–5 syllable count, or a limerick with its AABBA rhyme scheme, Gherkin is a framework for structuring your user poetry. Gherkin syntax uses “Given”, “When”, and “Then” to describe how a feature is expected to behave. This, in conjunction with another verse to express the motivation, will ensure that your stories are ready to be picked up by the development team.

User poems have two verses: The Motivation, and The Acceptance Criteria.

The Motivation

The Motivation verse conveys why this story is important to the user. When the development team understands the reason a story is being developed, they’re empowered to recommend other methods that may achieve the same goal. These new ideas may be less complex or “cheaper”, and the team can decide how to move forward.

Here’s an example of how you can reformat the motivation for a story into a user poem.

The original user haiku:

There's a customer
Who needs to update her name
Since her name has changed

The updated “As a … I want … Because …” user poem:

As an existing customer
I want to update my account information
Because I changed my real name

Both stories are quite elegant, but the second one provides more structure. When all user poems are written in the same format, the team will be able to quickly determine who the feature is for, what they want, and why they want it.

The Acceptance Criteria

The Acceptance Criteria verse lets the development team know what needs to be done. A feature is acceptable if it’s implemented in a manner that adheres to this criteria. It’s important to note that Acceptance Criteria is just the start of a conversation, not the entire conversation. These aren’t meant to be epic requirement specifications to rival the length of Beowulf or Dante’s Inferno. In fact, they aren’t even meant to answer all the questions that the development team might ask. If the team needs more detail or a clarification on the expectations, an in-person conversation is the best way to go.

Here’s an example of converting a user story into Given-When-Then format.

The original user limerick:

There once was a user named Kate
Who just got to marry her soul mate
She changed her last name
From Wilson to Haim
But now her profile’s out of date

The updated “Given-When-Then” user poem:

Given I am logged in
When I edit my profile
Then I should be able to change my name
And I should see the updated name in my account info

Notice that there’s an extra “And”. This particular form of poetry has a few variations. You can add a few “And” lines onto the end as needed. You can even have more than one entire Given-When-Then verse. But, you should use these extra lines and verses sparingly to avoid writing user stories that are too big. If you can break your story into separate stories that each provide value, you might find that it makes sense to prioritize one of them very differently than the other. Or, better still, perhaps you don’t even need both of those stories for your MVP.

The structured format here makes it very easy for anyone to understand the expected behavior for this story. As with the motivation verse, when all stories are written in this format, the team starts to get used to the rhythm: set up the scenario as per the Given, perform the key actions in the When, and confirm that everything happens according to the Then.

So, when are we going to start seeing user poems in creative writing journals?