Repository navigation
Story Writing
It is much harder to write simple, concise and coherent stories than sloppy ones. Take the same level of care when crafting a story, as you would like a developer to use when they are writing the code.
A good story is an invitation to a conversation, not a replacement for one. Stories should be small. It is rare for a 2 day story to take 4, but it is not uncommon for a 5 day story to take 10. They should deliver business value. Ideally a story should be free from dependencies, although is may be difficult to achieve.
A story can be broken down into the following sections, in order of importance...
- Title
- Benefits
- Acceptance Criteria
- Background
- Things to consider
See here for an example.
The story title should be punchy and meaningful. Where possible it should be written with a non technical audience in mind, e.g.
Automatically invite new staff to the company portal
It's fashionable for stories to use the following formula...
I as a portal administrator would like to invite new staff to the company portal automatically
so that I can save time
This is an anti-pattern. Such stories are dull and uninspiring. The authors often resort to a generic user and benefit. Worst of all when displayed on an electronic board may be truncated. I've seen Jira boards with 300 stories titled "I as a user would like...". They only had the story number to differentiate them.
A preferable alternative to the "I as a user" anti-pattern are [personas]. A good persona helps us identify with types of users, and if well written will tell us what behaviour we should aim to change.
Peter: Automatically invite new staff to the company portal
The "so that" part of the "I as a user" anti-pattern is valuable. People buy benefits not products/services - if we can't articulate the benefit of a story, why would we implement it? The benefits also provide context. Without context the developers are less likely to spot incorrect assumptions or inconsistencies. Attempting to squeeze the benefits of a story into a single sentence is often unrealistic. Instead record it in the story content.
Benefits:
* Staff no longer need to submit an access request
* Staff can access portal without delay
* Portal administrators can spend their time on more important things
Acceptance criteria should reflect business requirements, not a solution, e.g.
- [ ] New staff are automatically invited to the portal
- [ ] Staff are not invited the portal if
- [ ] they have a pending invitation
- [ ] they are currently a member of the school's portal
- [ ] they were previously removed from the portal by an administrator
When using tools like GitHub to track work, the acceptance criteria should be prominent in the issue (e.g. entered at the very top of the issue), to avoid wasting time during stand-ups.
Often the story author will be aware of likely pitfalls or potential solutions. A well functioning agile project would solve this through discussion, pairing and pair rotation, but this is not always practical if the team is distributed and working across timezones. Regrettably the engineers with the experience to design a solution are not always on-hand. Therefore including some guidance may be necessary, however this should not be a series of instructions. Sustainable teams must think for themselves, and key information may be missing at time of story writing.