Principles To Effective Story Writing: The Pivotal Labs Way

By Ryan Jones (Product Manager) & Pablo Schuhmacher (Product Manager)

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.

Story Writing: Guiding Principles

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:

Different Types of Stories:

Features/User Stories: 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:

  • Title: The title should be short, descriptive, and include the specific user/persona. For example, the user/persona should either be the specific type of user (e.g., editor) or the persona name (e.g., Jill) rather than just “user.” This also works for users that are not people but systems (e.g., “Purchasing API”).
  • Business case: Who wants the functionality, why, and to what end? This is incorporated so that everyone on the team understands why the feature is being added. If you cannot think of a reason, then it’s worth reassessing if the feature should be included. The business case also allows others on the team to think if there is a better user experience than the one provided.
  • Acceptance criteria: This defines what you will walk through to make sure that the story is completed. Developers working on the story should also walk through the acceptance criteria before delivering. At Pivotal, our beginning template for acceptance criteria is written in the Gherkin language. The Gherkin language was originally created for Cucumber, a Ruby testing suite, and is meant to “enforce firm, unambiguous requirements … and a script for automated testing.” Keep in mind that good feature stories should not, however, be prescriptive in implementation details.The syntax is as follows: GIVEN [necessary context] WHEN [action] THEN [reaction]. Sometimes it helps to walk backwards to determine your GIVEN (examples to follow). If you find yourself writing multiple “and”s in the acceptance criteria, that is a smell test that indicates you should split the story into two or more.
  • Notes: Include additional information needed for the story, such as design notes (which might point out changes to mocks) or developer notes (which might provide insight that could help developers deliver the story).
  • Resources: Add mocks, wireframes, user flows, links, and other assets to help deliver the feature story.
  • Labels: This includes epics (larger overarching features), build #s, users, etc. These are used most effectively to help group the stories together.

Bugs: A bug is a defect in a feature that has already been 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:

  • Title: This should be short and descriptive.
  • Description: What is currently happening? What should be happening?
  • Instructions: Outline the steps to reproduce it.
  • Resources: Include screenshots and other assets to help explain/show the bug.

Chores: 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:

  • Title: This should be short and descriptive.
  • Description: Why is it needed? Does it help the team go faster or is it a dependency that could cause problems in the codebase if it’s not done?
  • Resources: Including instructions, additional context, or other assets that help execute the chore.

Feature 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 & paste version]

Bug Template [copy & 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.

Examples of Well-Written Stories:

Feature Stories

Using a persona name for a consumer-facing product

Using a persona name in an internal tool

Bug

Chores