Ask how stories are written in an Agile or Scrum environment, and you will inevitably get the “As a …, I want …, so that…” bog-standard, cookie-cutter answer. But ask yourself this, is that all you write in a story?
User stories in the Agile world is a means to achieving a goal in software applications. The umbrella definition, if I may call out, is a placeholder for a conversation. We say stories are a shorter, leaner, lighter version of capturing a business requirement, whilst never, ever, intended to replace a good conversation.
This is a perfect prelude to a modern myth: that user stories do not need to be written with the standardised business requirements document format, with use cases, UML / sequence / state diagrams, compatibility matrix and all their glory in the old world…. which means they do not need to be written with the same level of rigour. Anyone who could muster “As a .. I want ..” can therefore write user stories.
In truth, rigour is thoroughly practised, if not more so than requirements in the traditional sense; the rigour and discipline are actually found not in the documentation format but in the content. Having written user stories for years at ThoughtWorks, there are a set of principles that really help me to turn stories from good to great.
1. Get your story right
As an editor,
I want to create drafts for my articles before publishing,
So that I can show them to the editor-in-chief for tweaks before my articles goes out.
I have lost count on projects where stories are incomplete. How many times have you seen the “so that” part missing? It is often the most difficult part to express in the entire story, so many people just leave it out. Do not make this mistake. The story format is laid out like this for a very good, real, reason. It is so difficult to get this part right, let alone having this part, because it forces the author to think hard about WHY this story needs to exist, the very reason for being. It is justifying why the company should spend its money on developing this over another story. Which means that if there is no real reason for it to be there, it will be de-prioritised or deleted altogether. However if you omitted this part, there is very little telling on the true value it delivers. It will just be a list of wild wishes mixed with legitimate wants and needs. It also encourages behaviours like “whomever shouts the loudest gets the most stories that they want” — ending up in this situation is a sad place to be, really.
Another pet-hate is seeing “As a user” for all hundreds of stories. Do you have only one user? Really? Just one type? No personas whatsoever? … I will gracefully leave this out for another time.
2. The unwritten rule of what goes inside
I always have at the ready The List, regardless of what domain I am working in. The List contains the cornerstones that tell you whether your stories have the minimum sufficient amount of information to express what you want to do, for the development team:
- Story: As a, I want, so that
- Technical notes
- Out of scope
- Acceptance criteria
Going through The List really spells out whether you have gathered enough information to begin development. It is no longer acceptable to write half-baked ideas and masquerade them as requirements, under the Agile or Scrum label. Please, don’t blame Agile or Scrum when you are really just lazy; being Agile does not mean we have any less attention to detail. It is focusing on the right level of detail in the right places at the right time.
3. Choose your words carefully
As you are writing less, really mean what you say when you say it. Make sure you are using the same language as the domain and not adding another hoop for the team to jump through. When you are writing stories, make sure you are referring to the terms correctly and consistently. Been using the word graph? Don’t switch to say chart mid-story. Even if they mean the same or similar things to you it would not always be the case for someone else. I have a few more examples:
- Picture vs. Image vs. Illustration vs. Diagram vs. Graphic
- Description vs. Content vs. Blurb vs. Stub vs. Paragraph
- Number vs. Digit vs. Character
- Table vs. Chart
Same goes to when you are talking to QAs, developers, product managers and stakeholders. Be aware that terms and names are used for mapping out the domain model, lives in the codebase as well as unit tests, functional tests and end-to-end tests … so being consistent will only help everyone understand what you mean clearly.
4. Use acronyms sparingly
Do not build the barrier to communication higher by putting in loads and loads of (even commonly known) acronyms. One person’s understanding of CMS, CRM, GDP, SAT, SIT is quite different to another.
5. Convention over OVER-complication
In life and in story writing, use plain English as much as possible, strive to use this rule as often as possible. There is no better way to put this.
Whether you like to admit it or not, no one wants to read reams and reams of waffle when they are really looking for the boiled down facts — so show only the boiled down facts — and show it clearly. Lots of analysts grow frustrated or disheartened, or both, when they found out no-one was really reading their documentation. Worse still, many miscommunication and misunderstandings stem from the fact that implied requirements are hidden in paragraphs of text when they should be clearly spelled out line by line. Be explicit, unambiguous and concise in your words. Adding unnecessary terms to things can only confuse people and it is everywhere: words like framework, repository, structure, XYZ manager when you are naming features may be intelligent-sounding but really build towards the fluff that people learn to disregard. Shock horror, not (!)
I hope this is useful. As with most things in a collaborative environment, ask for feedback from your peers if you are unsure of the right level of detail; you never know, a little feedback goes a long way in the world of continuous learning : )