Ways to approach technical story writing
I’m assuming you’re familiar with traditional story writing and our process here at Pivotal Labs. If you’re not, perhaps you should check out this blogpost by my awesome colleagues first for general story writing principles.
A vast majority of the time our general story writing process just works and should be the default path you take. However, some products or projects might have additional technical complexities or may be purely backend focused that can lead to some tweaks to story writing. I hope to outline a few examples below as an approach to writing technical stories.
If you’re a PM tasked to work on your first technical product backlog, here are a few things to keep in mind:
- Start out with traditional story writing principles
- Don’t fear the technical jargon and focus on a conceptual understanding
- Buddy up with the technical lead or other engineers for any help
- Be willing to adapt and iterate on your story writing to help your team
Start with Standard story writing
I would always try to fit stories into our standard story writing process first and then make adjustments to emerge into what works best for your team. As an example, let’s say I’m working on stories for an API. I might start by writing a story like this:
As a developer, I want to use the Ops Manager API so that I can hit the API with invalid user parameters to see error responses.
GIVEN I have an invalid user token and/or an invalid ID
WHEN I post to the Ops Manager API
THEN I will receive the error response code and message string
The story writing for this example isn’t so bad, right? The story is written from the standpoint of the API consumer and hence a user perspective. Notice the acceptance criteria still fits into the standard flow using gherkin. I focused on getting the high level concept written so that I can begin a conversation with a developer.
Then I can work with developers, look at documentation or expand pre-IPM time to round out this story with more specific technical details. IPM is our iteration planning meeting (think sprint planning) and you can find out more information about it through the link.
In the end, the API story will morph into something like this.
Pro-tip is to use `back ticks` in tracker markdown to format any code written in the story. Your story will suddenly feel way more structured.
A question I’ve often got asked from other PMs is if listing the response code and table are implementation details that should be left to the developers when the story is started. I don’t consider them to be since they are part of the acceptance criteria. How the developer implements the API is up to the dev pair, but I have a specific response that I’m looking for to accept it. You can also break down each API response into a different story depending on the complexity. Since all of these cases are errors, I’ve decided to list them together.
Accepting technical stories
Another challenge might be how to accept this story once completed since it’s not user facing and you’re not an API. You’re a human! You can talk about this with the developers to set expectations during pre-IPM or IPM but essentially there are several ways you can end up accepting this story. If there are going to be multiple API stories one way is to have the developers create a simple page where you could type in the token and ID and see the API responses on the page as well. Mock UI can be extremely helpful. Or you could pair with the developers for acceptance and look at the console with them. There are even services like getpostman.com that can help you run, test, or document API stories. Find out what works for the team with the idea that over time you’d want to be able to accept stories on your own.
System to system stories
There are times when your stories may be from a system to another system in which case it may make more sense for your persona to be a system instead of a user.
As a mobile app, I should be able to get ignition times so that I can start trip calculations.
GIVEN a vehicle trip has been started
WHEN the mobile app requests the latest start times
THEN the backend provides the vehicle ignition event timing
This is an example of a backend story needed for a mobile app of a car service. The mobile app (system) is treated as the persona and the “WHEN” is the action taken by the system. The mobile app could be running in the background and even requesting data without any human interaction.
There could even be times when your stories don’t have any user facing benefit at all, but is still necessary to break up developer work and track velocity as a new story. Don’t fret the system persona. Last I heard, robots are cool.
Adapting your story writing
Every project is slightly different which presents new challenges. I’m currently on a project that involves only a front-end rewrite of an existing technical product. Thus we’ve slowly adapted story writing for our specific team (after many iterations). Let’s take a look at one of my stories in the backlog.
Aren’t those implementation details listed? You have created product management sin! Please put down your weapons, we’ve adapted our story writing as a team for a few reasons.
- Better estimation for stories
- Helping ramp up new people to a super large codebase
- Dev notes are for documenting endpoints that are not changing
What are appropriate dev notes?
So for these kinds of stories we stuck to the traditional story writing except we have more detailed technical dev notes for each story filled out before IPM so that we can more accurately estimate each story. The dev notes do contain “implementation details”, but we only list backend endpoints that we have to deal with since our project is only focused on the front end. These aren’t implementation details we can change for this specific project and we often include links to specific parts of the code to reference since this is a rewrite initiative.
We’re still iterating a bunch on this approach. However, when we walk through Pre-IPM we make sure that the story is complete from a user and product perspective. Then we may spend some time looking through the codebase for the endpoints that are needed to fill out the dev notes. The downsides to this is that Pre-IPM time can be significantly longer as we’ve got to dig through the backend code to find which properties exist for us to call to round out the story. We have had a developer get carried away in this process and end up implementing the story on the spot. Also, there’s a gray line to not actually impose architectural details or dictate how it would be implemented outside of the non-changing endpoints. We help mitigate this by having the developers fill out the dev notes in pairs and by time boxing story research. We’re currently limiting code diving and documentation to 20 minutes per story.
In summary, while writing technical stories can be slightly different depending on the specifics of a project you can always start out with the tried and true Pivotal process and adapt from there. You should feel empowered to ask any questions needed to gain an overall understanding of technical concepts. I’d think you’d be surprised how often the story writing will be the same as general story writing. Just don’t let the technical verbiage cloudy your wise product judgement.
Another blogpost by a fellow Pivotal product manager:
- More information on technical backlog examples
