The Thorough User Story
If you’re a product manager working on a software project, you probably spend a large chunk of your time communicating new requirements to designers and engineers. The temptation for many PMs is to throw one or two “user story” statements into a ticket (for example “As a lawyer I want to find legal documents by case number so that I can do my job faster”), ask the designer to attach a mockup to the ticket, and throw the ticket over the fence into Engineering Land. Any more detail than that and you risk writing a “specification” — something frowned upon in the world of Agile development.
While such a minimal approach to documentation can save time upfront, it ultimately leaves the door open for a variety of risks that can delay a project, waste work, and cause frustration. Skimping on upfront design and documentation places the success of the project on a host of assumptions: that everyone attends design meetings and takes notes. That you’ll be there to answer questions when a feature is built. That the engineer you originally discussed a feature with is the one that ends up building it. That everyone asks questions. That the engineers are in tune enough with the roadmap to architect features in a forward-thinking way. That the testing team was taking notes when you discussed edge cases with an engineer. The list goes on. And these things add up — the larger the team the more severe the consequences of under-communication. As a PM you can mitigate such risks by including a few details in your user stories and tickets:
BUSINESS CONTEXT
WHAT: Clearly describe the business need and context before you get into your requirements / acceptance criteria / design. User story statements are a big part of this but don’t forget to mention context around clients, urgency, and competitors.
WHY: Let’s say you’re trying to match a competitor’s search capabilities and you come up with an idea for a fancy search box. You document the solution in a ticket and slide it over to the designer for a UI mockup. If you don’t mention your competitor in the ticket, the designer is unlikely to propose other (potentially better) solutions or to study that competitor’s UI. Likewise, let’s say that your search box was requested by a specific customer. If you don’t record this information, the QA team will not know to test with the proper customer-specific sample data or testing environment.
PRODUCT & PROJECT CONTEXT
WHAT: Before getting into requirements, add some background into how users solve the problem today, what — if any — foundational elements have already been built, and how this work fits into the whole. In your mockups, use color coding or annotations to clarify which parts of a screen are specific to this ticket. If you’re enhancing an existing feature, remind the team what other parts of the product this feature affects and where else it appears. If this is a larger story, mention the ticket breakdown and add some links.
WHY: As a PM it’s easy to forget that most of your team is focusing on implementation details and specific feature areas. No one knows the whole product on holistic functional level as well as you do. Small reminders like this help avoid many ugly situations, from “Oh I didn’t know that part was built yet … so I built it again”, to “I didn’t know that UI element was shared across several screens so I only designed/tested on this screen”, “I didn’t know that feature also did X”, and “I didn’t know this was a temporary stop-gap solution so I spent a long time optimizing it”.
PM OWNER
WHAT: Record a single clear PM owner for each ticket. Depending on your ticket management system this may be as simple as looking at who created the ticket. The clearest way is to simply list it at the top of the user story.
WHY: Team members often don’t know where to go for clarifications. Even if you’ve recorded the work required in excruciating detail, the development team will likely have additional questions. And if you have more than one PM on the same product this can get confusing. The best case scenario is that another PM gets distracted and engineers waste time tracking down answers. The worst case scenario is that another PM attempts to be useful and gives engineers the wrong answer. I’ve seen this happen — with an end result of wasted work. This isn’t limited to development either. After a feature is built, the QA and support team will have questions about intended behavior that may not be clear from your user story or documentation.
SUMMARY / ACCEPTANCE CRITERIA
WHAT: In a few bullet points, address what changes will be made to the software on the frontend and backend. This is more solution-specific than user story statements but short enough to be quickly skimmed.
WHY: A bulletpoint summary of feature work has many uses. It helps engineers provide a rough estimate without needing to delve into details. It helps the team properly assign work to subject matter experts. It inspires questions while still early enough for a design to be changed. It makes it easier for executives and managers to get visibility into what’s coming up without relying on ticket titles. And it makes it easier for engineers to navigate details and mockups down the line. And, finally, it helps engineers and the QA team confirm that nothing significant has been left out before going through a full testing cycle.
NON-GOALS & FUTURE FEATURES
WHAT: List what problems you don’t want to solve as part of this ticket, what solutions are off the table, and what related work is coming up in the future.
WHY: This is an often overlooked detail that can have a big impact. To go back to our earlier example: if you’re building a search box it’s worth mentioning that you don’t care about auto-suggest. This not only helps designers scope their proposals and avoid wasting work but it also helps engineers provide better estimates. Finally, if any of your non-goals are things that WILL come up in the future, mention this (and potentially link to appropriate tickets in the roadmap). Remember — as PM you are an expert on the product roadmap. Knowing what’s coming up will ensure that engineers come up with a forward-looking architecture and spend less time down the road uprooting and rewriting code.
OPTIONAL ENHANCEMENTS
WHAT: Make it clear which parts of the story are optional nice-to-haves. These are typically little embellishments and polish ideas that you can live without — especially if you’re short on time. They’re not non-goals but they’re also not requirements. It’s also worth “time boxing” these — for example by specifying that they should only be tackled if they’re likely to take less than 45 minutes.
WHY: Simply put, this is a way to maximize small touches and other optional details that delight users while reducing the risk of delaying other critical work or cluttering up your backlog. If a designer suggests a fancy tooltip but you’re unsure whether it would add significant development effort, mark it as optional. It may end up being something that can be built in 15 minutes, in which case it was worth bringing up and building out. However, if it ends up being a significant undertaking you don’t want to find out that other work was delayed because your team interpreted it as a hard requirement and spent time building it.
DESIGN DETAILS
WHAT: The devil is in the details. Even the smallest features have a number of tiny details that end up being overlooked because no one bothered to spell them out. This translates into incorrect estimates, bad user experiences, and disruptions down the line. As you work closely with engineers you’ll develop a better intuition for these. You’ll also want to work with designers (especially those new to interactive design) to ensure that they’re considering these kinds of questions ahead of time:
- FUNCTIONAL: which fields in a form are required? What is their max and min length? Would you prefer a list to infinitely scroll or paginate? When the user updates something, what other parts of the screen should refresh?
- ERRORS: what are all of the possible error states and what messages should users be shown?
- INTERACTIONS: what are the hover behaviors over links and buttons? Which elements should scroll with the page and which ones should stay in a fixed position? When the page is resizing, does the side pane stay the same pixel width or does it resize proportionally?
- EDGE CASES: what happens if a user tries to deactivate an account that’s been deleted? What happens if you try to reimburse money to an expired credit card?
WHY: Omitting details makes for a sloppy product and an unhappy team down the line. While conscientious developers will fill in some of the blanks, you risk frustrating your users, shipping unprofessional copy and UIs, overwhelming the support and QA teams, and interrupting the dev team with frequent small fixes.
This is not an exhaustive list. Neither are any of these details universally useful. Small experienced teams may not benefit from all of these. Some of the details may be overkill for tiny features. At the end of the day it’s up to you and your team to decide which of the information above is worth documenting. The answer may change over time and as your team grows. Try out different documentation approaches — especially if you find yourself hitting any of the pitfalls above — and see if they benefit your team.