Different teams across projects and companies have different styles of story writing. Ultimately, it is up to you and the team to figure out what is most effective given the goals and context of the project. However, the core principles that guide our story writing here at Pivotal Labs can be used regardless of style or variation in either process or syntax. While the differing views on the “best way” to write stories can make it difficult to determine the most effective approach, there are a few core principles that guide our story writing. In this post, we’ll explore the three most common types of stories that you can create in Pivotal Tracker and the core principles that inform how we write stories.
First and foremost, stories are placeholders for further conversations and context on conversations already had. We write stories to address a feature, bug, or chore, and then we discuss those stories—usually with our engineering team—to surface any lack of clarity or concern around delivering the story in question. Because of this, stories do not need to include every little detail, but should be a reminder of what was talked about and include everything at a high level.
It is also important to remember that stories should state the what, not the how (e.g., “Improve search response by 15 seconds” vs. “Do not perform a full-table indexing on every database update”). Stories are not meant to be technically prescriptive; that is, they do not need to specify any information on how exactly your engineering team could implement the functionality in question. Stories clarify the reason for the functionality and what specifically that functionality is.
All stories should follow the INVEST model:
Feature stories are designed to explain the who, what, and why of the smallest incremental feature that can be added to a product that delivers user value. Feature stories are pointed by the development team and are estimated by complexity rather than by the time it will take to complete the feature. They are written from the user’s perspective and act as lightweight requirements documentation for a development team. Following the INVEST model, they should be independent and create clear value to the user. For example, each button should be added in conjunction with a feature instead of having a story that creates a row of buttons that are not connected to features. While features and user stories are often used interchangeably, for the sake of clarity—and to be consistent with Tracker’s naming conventions —we will refer to this kind of story only as a feature story throughout the rest of this post. Feature stories should include several things:
A bug is a defect in a feature that has already been accepted, regardless of when it was accepted. You should not use bugs to detail new features and functionality (e.g., “Price should be non-negative” or “Login button doesn’t work”). Bugs are directly related to features that have already been delivered and provide no new user value, which is why they do not have points. The other reason they do not have points is that bugs can be impossible to estimate and could take 30 seconds or 30 days to resolve.
Bugs should include this information:
A chore is a story that is necessary but provides no direct, obvious value to the user (e.g., “Setup new domain and wildcard SSL certificate to create test environments” or “Evaluate tools for system troubleshooting”). Chores can represent technical debt and/or points of dependency on other teams. Chores are not estimated (i.e., pointed), as they do not contribute user value directly. This means that if a chore feels like it provides user value then it should be incorporated into a feature story. For example, if you are using an analytics service, the additional complexity of the service setup should be taken into account in the first analytics feature story, rather than separated out as a chore.
Chores should include this information:
User and Bug Story Templates
The templates below are a great starting point for writing feature stories and bugs. We haven’t included a template for chores as they vary significantly, but we have provided examples of chores at the end of the post. These templates have been iterated on over the years to provide consistency, clarity, and simplicity. For easy access, we copy and paste them into the Icebox with a title of, “Cheat Sheet: Story Template—Reference When Writing Feature Stories” and “Cheat Sheet: Bug Template—Reference When Writing Bugs.”
Feature Story Template (copy and paste version)
Bug Template (copy and paste version)
Conclusion
We have no doubt that as you become comfortable with story writing, you will formulate your own style that works best for your team or project and undoubtedly move away from the basic templates that we have provided. To that end, we’ve included below what we consider to be examples of great stories. As you’ll see, while they vary in style and syntax, they exemplify the core principles that we’ve highlighted in this post.
Feature Stories
Using a persona name for a consumer-facing product.
Using a position name instead of persona name in an internal tool.
Bug
Chores
This article was co-written by Ryan Jones (Product Manager) and Pablo Schuhmacher (Product Manager).
Category: Productivity
Tags: How to
