Agile Notes:
Why Story Cards Matter
One of the popular memes in the Agile software movement is an emphasis on low ceremony. Processes should be lightweight; easy to describe, easy to follow, easy to amend. Steps which don’t add clear, compelling value are on the chopping block. In many projects, formal story cards end up on the block…and this is unfortunate. Although they may seem ceremonious, well-formatted story cards add critical value to the software development process.
Clause Celeb:
The Main Parts of a Good Story Card
1. Include the Role or Type of User
As a user who wants to buy widgets ...
This is an important piece of context. Not only does the user’s role help disambiguate functional differences between different types of users, it also helps us to mentally step into the shoes of the user referenced.
2. In Order To See The Big Picture
... In order to learn about widgets available in my area ...
By including an in order to clause, we get a succinct reminder of the user’s overarching objective. This will help us to uncover additional stories, e.g. highlighting the lowest price in bold print, etc.
3. Write Stories In the First Person
... I want to see a list of widgets ...
By writing (and thus reading) stories in the first person, we automatically roleplay, and we begin to see the application through the user’s eyes.
4. So That We Remember What We’re Doing Here
... So that I can find the cheapest widget
The so that clause is narrower in context than the in order to clause, and helps clarify just exactly what our user is trying to do in this feature.
Handy Annotations
In addition to the core clauses of a good story card, there are a few other bits of information which can be helpful when added to a particular note card.
A Working Title
A one-line (or one-word) title can be helpful for a couple of reasons. First, when discussing various features, it’s helpful to be able to talk about a particular card without reciting the whole card. So by titling our card “Widgets List”, we can refer to it. If somebody doesn’t know what “Widgets List” means, they can go find the card with that title and read it.
Likewise, that title is handy for stuffing into a version control commit message:
Completed the 'Widgets List' feature.
If you’re using the Pomodoro Technique, the card title makes a fabulous task description:
Worked on the "Widgets List" story card
Who’s On First
... Joel
Another helpful annotation is the name of the person/people who is/are working on that card. This helps us to know who to talk to later when we have questions about that feature.
Let’s Get This Party Started (And Stopped)
... Started 09/19/09 Finished 09/21/09
When you pick up a card to start working on it, it’s helpful to indicate the date when you started that card. Should you add the time as well? It depends on the granularity of your cards and the relative velocity of each card. If each card is measured in days, then you may not care to put the time. But if you’re able to knock out some cards in a few hours, then the start time might be useful.
Likewise, by adding the date (and time, if applicable) that you finished the card, you’ll be able to do meaningful velocity tracking for the project. If you’re using Kanban and have other queues after development, such as a QA queue, you might want to substitute Finished for something like Sent To QA.
If you want to track interruptions in a particular story, you can also add Paused and Resumed timestamps as well. Of course, this may add a lot of extra information to your cards, so you should consider whether you really need that information. For example, if you are a developer who serves multiple roles, or who must be available to help people in another department, pause/resume metrics might help you to make the case to your manager/team that something needs to be done to shift some of those responsibilities off your plate, or at least help manage those interruptions.
Show Some Constraints
...
Constraint: these discounts should only be visible on
Tuesdays and Thursdays. On other days,
show "no discounts available."
...
Some stories come with those peculiar edge cases where we want the feature to do things a bit differently than normal. So it’s helpful to write those as additional constraints on the card. In order to keep the front of the card fairly legible and clean, I like to list the constraints on the back of the card, but that’s really up to you.
Pick on Somebody Your Own Size
Estimated: 3pts ...
Before you begin working on a story card, it’s a good idea to add to the card an estimate of the amount of effort required for that feature. Some teams put estimates in terms of literal time (hours, days), some use “points” and and some, like Leandog Agile Studio, use T-shirt sizes. Whatever metric you decide to use, the objective in estimating is to improve the team’s ability to estimate over time.
Estimating software projects is hard. There are so many unknowns, so many variables. Nevertheless, some people are better at estimating than others. So it stands to reason that estimation is a skill which can be improved. The key to improving your estimating skills is to keep estimating, and then measure how close you were after the fact. By adding an estimate to each story card, you’ll be able to measure how close your estimates come to reality, and you’ll begin to see which scenarios and factors contribute to your most inaccurate estimates.
Story Writing Tips
When writing story cards, there are a few things to keep in mind which will vastly simplify development later.
- Keep implementation details out of your stories: story cards should describe what the user will do, not how the system will work.
- Sometimes even keep site map details out of stories: you can include where the feature will be seen in the site if it’s relevant to the way the feature will work. For instance, when showing a list of message recipients, it might be important to specify that they should appear on the “show message” page. But if the product owner or client hasn’t specified where on the site a certain feature should appear, don’t embroider the story card by making up a location.
- Story cards work just as well in reverse: sometimes you may have a client who resists writing story cards in the format you’re asking for. That’s fine, simply write up the story card yourself, and then ask the client to read it and confirm that it describes the feature accurately. In the same way that a client’s story card effectively communicates a feature to the developers, it also communicates back to the client.
- Don’t toss out the one-word story card! Sometimes, when you know about a certain feature, but haven’t hashed out all its details, it’s helpful to just jot down a very short description of the feature, such as “Archived Messages.” This lets us remember that there is supposed to be a feature relating to the archiving of messages in the app, but the low detail indicates that there is still much discussion about this feature which must take place. Very often these single-phrase story cards end up being broken into several story cards. The point is that we’d never pickup a story card with nothing on it but archived messages and start writing code for it. This isn’t so much a story card as it is a bookmark which points to a rather in-depth conversation which either wasn’t finished or was never started.
- Don’t write a bajillion stories at once. Write only enough for the next iteration or at most two iterations. The reason for this is that inevitably the details of the application will change as the project proceeds. These changes come from shifting requirements. But even more importantly they come from better understanding of the application’s domain. I have never yet seen a client, product owner or development team who could keep all the feature details of a large project in his or her head. Inevitably we use a kind of mental shorthand which fails to uncover inconsistencies or contradictions. We only uncover those things as we go through the development process. So if you spend a large amount of time writing up huge numbers of detailed story cards at the outset, you have suddenly created a large body of work which will need revision later. It’s better to write detailed story cards for the next few features you intend to work on, and write one-liner or single-phrase cards for other features. As you get ready to move on to those short form cards, break them down and write detailed stories for them.
Bad Card Smells
- You can’t tell, from reading a story card, whether it describes something the development team must do just once, or whether it’s something the users will do every day.
- There is no way to tell who will be doing the action described in the card.
- There is no clue what anyone would hope to gain by using this feature.
- There is no indication how this feature might relate to or be similar to other features in the application.
- The card is telling you (the developer) to do something instead of describing how a user will do something.
Happily Ever After
These various story card parts help the developer to mentally align to the user’s specific position and vector so that he or she can quickly and decisively build exactly the functionality that is needed. Story cards should be short and easy to read. By lightly formalizing their format, you can improve the speed and accuracy of comprehension for everyone on the team. Story cards don’t eliminate the need to have subsequent conversations with the client or product owner. They just make those conversations shorter and more productive.
