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.
What is a 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.
Why create product specs?
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.
What should you include on a product spec?
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.
1. Who the product is for
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.
2. What problem you’re helping them solve
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.
3. Why your organization should build it
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.
4. What you plan to build to help solve that problem
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.
5. How you’ll know when what you’ve built is successful
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.
Example Product Specs
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.
Live Chat on Checkout spec document
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.
Credit Card Handling Feature Requirements
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.
CASL Compliance User Story
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.
Tips for writing product specs
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.
Define the what, not the how
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.
Be succinct
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.
Make the product spec easy to read
Organize your product spec in a way where information is easy to find. Subheadings, bullet points, tables, and images are your friends.
Clearly define scope.
Explicitly state what’s included in the product and what doesn’t need to be there.
Draft collaboratively
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.
Make it a living document
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.
Kent McDonald
Read also
Experience the new way of doing product management
Experience the new way of doing product management