How to write one user story:
Think of something that needs to change in your software, a problem with it.
You can come up with a name for the problem, or even some solution you've thought of for the solution. Write it down in whatever way comes to mind. It doesn't have to be perfect; it's a placeholder. But do try to think of it as a problem, even if you've written an action or a solution.
This is the first step. There are a few more:
Who has this problem? Is there a good way to describe a class or group of users? It doesn't have to be a fully developed "persona," it can be a specific person as long as that person is representative or individually important to the reason you're making the software.
What are they trying to do when they encounter the problem? Think about it, see if you can come up with more than one thing, write them down.
Why are they trying to do that? What are they trying to _accomplish,_ beyond the task?
Now that you can express what kind of person is having the problem in a way that makes it clear why they matter to you, what they're trying to do that you want to make possible or easier for them, and what their intent or goal is beyond that, you're ready to refine your placeholder into something that might be ready to work on. There's a template you can use, but you don't have to, it's just a way to capture these pieces of context that are necessary when reasoning about the user story.
The famous Connextra story format is:
_As an x_
_I want to y_
_so I can z_
It might look like:
_As a first-time user_
_I want to set a display name for myself_
_so I can be seen in a way that makes me feel like I belong_
It probably shouldn't look like:
_as a user_
_I want to have a display name_
_so people can tell me apart from other people_
The danger of the template is in producing a shallow understanding in a rush to fulfill its structural demand.
Since the template can be dangerous and can, after decades of abuse, be alienating, don't use it if people are allergic to it! And definitely don't make it mandatory!
But, you really should know who you think you're helping, and what you think you're helping them with, and why that matters in a way that someone can reason about out to things like the purpose of the product and the business.
So write that stuff down, using any format that helps you see who how and why quickly.
I like to try and take part of the middle part of the Connexta format and use it as the story title.
So from the above example the title of the story would become `set a display name`. In the style of sentence fragments used for other purposes, I don't capitalize it or end with a period.
This is the point at which I often regard the story as ready to discuss. You can get a lot more design and specification into a story, and each team has to set their own thresholds for things.
People often add two things that can be really useful in a lot of contexts: explicit Acceptance Criteria and some kind of wireframe or mockup.
In other cases, the intent is clear enough, even without this stuff, for everyone to figure out what they need to figure out from the story: what should I do, am I done doing it, was this done right, etc.
Decide if it's enough by talking about it with the people who will need to figure out the answers to those questions while they're using the story.
Visual resources can be attached or linked to, as can useful notes like established schemas or standards that might apply.
If they need contextualizing notes, you can add those.
People use something called Gherkin to add explicit acceptance criteria. It's a formalized "given x when y then z" template, and it has the same kinds of strengths and limitations as the connextra format.
You can do cool tooling things with it, but you can also "just" use it to structure your communication.
Honestly, writing out all the acceptance criteria is usually overproduction! You will calibrate what is enough in context with people over time.
Later, developers will probably write a bunch more test cases anyway. If they come up with some to talk about while you're planning, that's all good!
One of the main things I'd like for you to take from this is that while it is useful to have all these thoughts,
in a lot of cases,
when you write one story, you're done very quickly.
So much implicit information is developed and checked by coming up with the answers around who, what/how, and why, that people can often do what they need to do with just that. The rest of it is tools for generating additional alignment when that turns out not to be quite enough by itself.
The other question you'll be asking about a story is "is this more important than that?"
It's very important that question be satisfied, so you can prioritize, and reprioritize as your understanding changes.
So, that's how you write one user story.
Do just enough. Let the implicit work. Use the explicit to guide and patch it.
I've left out the part where you somehow learn and validate all this stuff you know about the people you're trying to help.
That's very important too, and if you find yourself struggling with any part of who what/how why or unable to come to consensus about given-when-then stuff,
you would probably benefit from talking to and watching more users to fuel your thinking.
fin
Oh one more thing actually:
I'm going to put some kind of short, free class/session/event together about this in the next couple weeks. Please reply or DM me if you're interested.
We'll also talk about when to split or combine stories, how to choose which stories to write, how to order them, and so on.
@anEXPer I do a lot of back-end integration work. When shoe-horned into the format, many stories look like “as system x I want to get data D in format F so I can act on it” (often there’s a “from system S” in there too, which I fight against; that’s meta info.), or else “as system S I want to safely expose data D so clients can act on it”.
There may be a special place in hell for those who insist on saying any system “wants” anything. I fight this shoehorning of system specs into user stories constantly. Has anyone seen a good format I can throw back at them?
@whybird @anEXPer You can see a small example of working this way in https://github.com/gdinwiddie/EquineHoroscope/tree/main
Feel free to ask me any questions have, or you can find the story of the development in the README and even more in https://leanpub.com/EvolutionaryAnatomy
@anEXPer My favourite one of those (for some very very small value of favourite) started out with:
As a product manager
I want my users to ...
:blobcatfacepalm: