How to Write Great Product Specifications
A flexible framework — and templates/examples from top product managers— for one of today’s most important business documents
Like most things in product management, writing a product specification is a variable and context-dependent exercise. Just like the role of a product manager can vary significantly from company to company, so can — and should — the exact content and structure of a product spec. These variations can stem from the unique function of product management at a given company, the nature of the product proposed, the makeup of the team that’s building it, and the maturity of the business it’s contributing to.
Just like the role of a product manager can vary significantly from company to company, so can — and should — the exact content and structure of a product spec.
That said, all product specs will generally pull from the same ‘master list’ of possible information and perspectives. It’s just a matter of curating which to include, which to exclude, and which to focus the most time and energy on — based on the variables above. As always, conciseness is a virtue in writing in a product spec, but only to the extent that it makes the spec more efficient and actionable for the audience reading/implementing it.
So what goes into a product spec?
Through Mural, we get to see a lot of product specs added by users from various companies. Below I’ve aggregated a masterlist of the types of information often included in these product specs — along with some learnings, best practices, and examples/templates here to help you as you write and perfect your own.
This masterlist breaks down roughly into the following three categories, discussed in depth below.
- Making the case: Why should we build this product and who it’s for
- In the Weeds: What exactly we’re building + what matters most
- Out of the Weeds: How we’ll measure success + decide what’s next
Making the Case: Why this Product, and for Whom?
1. Business context
Many product specs will need to explain the business and/or user behavioral case for building the feature being spec’d. In short, you’ll want to explain “why we’re building this feature now”. To do this, you should consider sharing:
- Data from preceding experiments/features that make a case for this feature
- A business imperative that is internal to your own company (e.g. preset quarterly goals or strategic need to focus on a new KPI)
- A broader change in your industry and/or prototypical customer’s life (e.g. introduction of new regulation or adoption of new technology)
This kind of context helps your team be more motivated to build what you’re proposing and more able to do it well — as they’ll be better able to make sound design & tech decisions on their own.
Example: Irene’s use case spec about a new “hiring targets” feature for StellarEmploy, featured as #1 on our Product Spec List, communicates a user behavioral case for this feature in a concise manner.
2. Goals
Beyond background context, you’ll almost always want to provide clarity on the goals of the feature being built — for the user, for your business, and/or both. A good product goal, like any other, should be specific & well-defined, measurable, achievable/realistic, and timeboxed for success.
Examples: Peter’s spec on credit card handling for Wing explains user goals well & concisely(#2 on our list), while the spec I wrote for the first direct lending experiment at Tala provides a helpful example of business goals (#3 here).
3. Audience
User personas and stories are other useful ways to provide helpful background context for your team. They are particularly useful for businesses that serve notably different types of customers/stakeholders/use cases and for features that are not inherently conversion driven. That is because conversion is usually about getting a user to do X or Y, whereas user personas/use cases are most helpful in understanding what the user already wants to do.
When modeling user personas, you will want to emphasize the ‘who’ that your product intends to serve, as well as what distinguishes them from others in the world, including customers/stakeholders in your business. When modeling user stories, you’ll then take the next step of deep-diving those personas’ pain points, and the how/why of their use of your new product.
Examples: Raven’s product assessment of Spotify’s customer journey (#9 on our list) exemplifies thoughtful user personas, while Bhuwan’s product brief template (#7 on the list) and Morgan’s spec for Relatio’s browser tool for text snippets (last on the page) provide sound user stories.
In the Weeds: What We’re Building + What Matters Most
After laying out your threshold points of context, you’ll of course need to detail what it is you’re seeking to build!
This will usually break down into some combination of:
1. Key Points & Definitions
This starts with a brief summary of the feature (which you may want to include earlier as a point of context) and can also include key assumptions you’re seeking to validate and/or acceptance criteria for user/behavioral goals.
Key assumptions are the threshold points of user behavior that you need this feature, product, or (even better) experiment to prove true in order to continue investing in its maintenance and improvement. These assumptions can range from validating that the problem you seek to solve is real (e.g. that users click to try the feature when given the opportunity) to validating that your proposed solution actually solves it (e.g. that they complete the/achieve the outcome you set out for them). Finally, acceptance criteria are the essential preconditions your product must satisfy in order for the user to make productive use of the feature(s) you’ve built. Acceptance criteria are crucially important for data-driven product managers as they also double as the things you, the PM, must feel confident about your product — in order for you to trust the data/feedback it will generate when launched.
Examples: Peter’s spec on credit card handling for Wing (#2 on our list) provides an example of acceptance criteria & key assumptions on a feature by feature basis, while Sumair’s spec on anti-spam compliance features (#8 on the list) does it at a higher “release” or “product” level.
Acceptance criteria are crucially important for data-driven product managers as they also double as the things you, the PM, must feel confident about your product — in order for you to trust the data/feedback it will generate when launched.
2. Tactical Details
The specific details in a spec will vary depending on the nature of the product being spec’d as well as the team/company building it. That said, they’ll usually boil down to a) front-end details like designs and interactions — which should be a narrative supplement to an Invision demo or set of mocks; and b) technical requirements.
Good Rules of thumb here are:
a) primarily front-end features (e.g. marketing page or new onboarding flows) will probably require more UI detail — unless, for there is already a very clear and consistent style guide or material design practice in place to streamline such decisions;
b) back-end intensive features will generally require more language around technical requirements and logic — unless, for example, the business is so mature that the behaviors it seeks to drive, and the levers available to do so, are now self-evident.
Examples: Peter’s spec on Wing’s Mobile Billing product(#10 our list) is a fantastic look at a thorogh presentation of functional requirements & details for a back-end intensive product. For front-end specing, you can
3. Prioritization
In addition to these details, it’s helpful to demonstrate and share a clear path to completion of the project at hand. This will often include a comprehensive list of tasks (perhaps via a task management tool like Trello or Asana) and/or timeline of how you’ll get to go-live. Finally, a ‘not-now’ list will help spell out for your team what is intentionally out of scope for this current build.
Examples: You can find an example of a ‘not-now’ list on my original spec about Mural (#6 on our product spec list).
Out of the Weeds: How Measure Success and Decide What’s Next
1. Measuring Success
A key piece of any product spec is identifying how you will define, measure, and evaluate success. This will usually come down to some sort of quantitative metric, or set thereof, that helps you assess the extent to which your product is achieving the behavioral and/or business goals it set out to achieve. That said, a good metric for success should not only help evaluate these top-level goals, but also one that is intuitively driven by other clear sub-metrics or levers.
For example, the top-level goal of a new onboarding flow may be to increase week 1 retention of new users. Tracking this metric will of course help you assess whether the flow is achieving its goal, but identifying & measuring its constituent sub-metrics, like % of new users who finish the flow & % of new users who open an onboarding email, will help your team understand why/why not the feature is working as hoped — and how you should prioritize future efforts accordingly.
Examples: Irene’s use case spec about a new “hiring targets” feature for StellarEmploy, featured as #1 on our Product Spec List, communicates simple KPIs to track for each feature spec’d, while my spec for the first direct lending experiment at Tala (#3 on the list) provides a helpful example of constitutent sub-metircs).
2. Feeback loops and preparing for the future
Building on your metrics for success, it’s important to provide specificity on your expected feedback loops. In particular, you’ll want to specify how long you are waiting to acquire sufficient data to evaluate success and at what cadence you’ll re-evaluate. You’ll also want to point out any known open questions, e.g. how many trainings a corporate customer will allow for its team on a new feature you’re building or how long it takes to get feedback from them about their experience using it.
Finally, and most importantly, you should include some basic scenario planning, laying out paths of future iterations, enhancements, and/or deprecations based on different types/levels of feedback, traction, or lackthereof.
Examples: The last spec on our list — re: a grocery finder for seniors quarantining during Covid — presents a good example of scenario planning for different types of early feedback/traction.
If you have any tips, ideas, or best practices for product managers write better product specs, I’d love to hear them! You can find me on Twitter, email (ajay@corelabs.xyz) and in the comments.
Mural is the fastest and easiest way for people to build and share beautiful portfolios of their work. It was born out of the frustration of trying to communicate the work that we do inside the constraints of a traditional resume or static website. We understand that work is dynamic, and careers don’t always fit into neat bullet points. We created Mural to help you always share the right work and right story with the right people.
Our newest feature, Workshop, now enables you to inspire others with your best work, and to find inspiration for new projects & tasks as well. What Dribbble and Behance have done for design, we see Workshop doing for product managers, marketers, and knowledge workers in general.
