When you talk to product managers these days about how they interact with their product teams, it’s quickly apparent the extent to which agile software development approaches have influenced how teams work.
One area of influence that has led to a lot of misunderstanding is the documentation that product teams use to communicate and remember information about the product itself. I’m talking here about the humble product specification or product spec.
I think it’s safe to say that few product managers or teams advocate for excruciatingly long product specs that go into way too much detail and take way too long to produce.
Just because you’re no longer expected to publish a tome for your next product, doesn’t mean there isn’t value in writing an effective product spec that can get your team on the same page about your product and keep them there.
Let’s look at what makes an effective product spec.
A product spec is a document that provides critical information to guide your product team as it designs, develops, and delivers your product.
This document helps your team build a shared understanding of your product and provides at-a-glance guidance for your team regarding what you’re building, why you’re building, and for whom you’re building it.
Product specs take a variety of forms and are sometimes referred to as product briefs.
The main reason you don’t want to get rid of product specs altogether is that they can clarify your thoughts about your product and share those thoughts with your product team.
As Gaurav Oberoi explains, “Effective product specs are a critical part of building great software. They force critical thinking up front, scale communication, and raise accountability — all leading to higher quality, lower schedule risk, and less wasted time.”
Specifically, product specs describe:
Who you’re building the product for
What problem you’re helping them solve
Why it makes sense for your organization to help them solve that problem
What you plan to build to help solve that problem
How you’ll know when what you’ve built is successful
Product specs provide context for your product that provides the purpose and drive to your product team (so that they know who they are helping).
When written properly, product specs provide guidelines for your product to define the problem you’re trying to solve, and provide some constraints on a solution. This description should keep your team focused, and help you avoid building a solution that won’t work.
The actual contents of your product spec depend on your product, your product team, and your chosen approach to product development.
As Ajay Rajani, co-founder of Mural, observes, “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.”
You’ll see these differences in the examples shared below. However, even with those differences, most product specs contain the following sections.
Your product spec should specifically identify the people you expect to buy and use your product. You want to know who you’re building your product for so you can identify their pain points and design your product to address them.
If you work on a B2B product, your users and customers may be different people, and it’s important to understand the difference. The people buying your product may look for distinct features in your product than those who will use it. You need to understand both groups so you can properly prioritize the features you add to your product.
You may include this context in your product spec or reference personas you create about your key users and customers.
Describe the pain points that your users and customers have, and why they would find value in having those pain points solved.
You may find it helpful to use one of the many user story formats to describe the problem you intend to solve. You could also describe the problem in terms of a job to be done.
Think of this information as the business case for your product. Sure, you’re helping your customers and users solve a problem, but is there something in it for your organization as well?
The explanation here should point to definite benefits to your business that your product brings, such as revenue growth, keeping customers, cutting costs, or helping to achieve your organization’s strategy.
This is where you describe the product in terms of how it provides a solution to the problem you’re solving.
You should provide enough information to act as a guideline for a solution without getting too specific. You want to give your team the ability to adjust to what they learn as they build the product.
You may list key acceptance criteria, key design constraints for user interfaces, and interface requirements for specific systems.
This section also highlights the functionalities that the product does and does not include.
The amount of detail in the section may start fairly light and expand as your product team builds out parts of the product. For example, you may start with a small set of high-level epics when you start working on your product, which gradually becomes a more fleshed-out product backlog with several detailed user stories.
This section describes the product metrics you use to determine if your product is a success. The product metrics you identify should act as leading indicators for the revenue, customer retention, or cost metric you identified in the Why your organization should build it section.
Product specs can take a variety of forms; from a documented titled product brief or product spec, to extra detail provided for user stories. Here are three examples of product specs.
Gaurav Oberoi shared this example product spec to help a vacation booking site improve its checkout conversion. For a description of how he wrote the spec and how he uses product specs in his work, you can read the accompanying article.
Peter Njongwe shared this product spec for credit card handling on Wing via Mural Workshop.
This product spec is an example of a more detailed product spec that goes into substantial detail about the intended solution.
Sumair Sattar shared this example of a user story detailing the requirements to enable Canadian Anti-Spam Law compliance with different channels of interactions at Medcan via Mural Workshop.
This example shows how some teams put the details around a product in supplemental documents to their user stories. Here, the team created a Confluence page they linked to the Jira issue that contained their user story.
Given that the form your product specs take depends on your product, your team, and your process some overall tips will help you make your product specs as effective as possible.
The product spec should describe your users and customers, the problem you’re trying to solve, and a general idea of the solution. Let your product team determine the details of how to build that solution.
The product spec should be a reference document, not a cure for insomnia. Find the right amount of detail that ensures understanding without overwhelming your reader.
Organize your product spec in a way where information is easy to find. Subheadings, bullet points, tables, and images are your friends.
Explicitly state what’s included in the product and what doesn’t need to be there.
Create the product spec jointly with your product team. The best way to build and maintain a shared understanding is to involve your product team in the document's creation.
Product specs don’t have to be set in concrete. Get feedback from those who aren’t involved in the initial writing about how to make the product spec easier to read.
Don’t put details you aren’t sure about in the product spec too early. Make it possible to revise the product spec as you work through building the product.
Product specs are a tool for building understanding and remembering what you agreed to.