How to write a product spec
Here at Productboard, we use product specifications (or “product specs”) to articulate a vision and plan for a product we’re developing. It outlines why we’re building that particular product or feature to guide development and to serve as a historical archive of why we did what we did.
Before getting into what we include in them, it’s important to recognize that a spec is a collaborative tool. It’s not a requirements document that conveys a final set of plans for building a feature. Our specs provide context, objectives, data, and well-defined needs so that our cross-functional teams can engage in conversation and make high-quality decisions about what precisely to build.
That’s why, similarly to when we talk about how to communicate your roadmaps, you need to connect with your colleagues and establish how this collaboration process should work for your organization. Understanding how your teams communicate and make decisions will guide you on what kind of document works best for you all. After deciding on that, choose a format that fits those needs. Some teams call them specs, briefs, one-pagers, feature kickoffs, or something else entirely. Whichever you choose, use a collaborative writing tool so anyone can leave comments (please don’t email around a PDF).
Our approach to the product spec
When creating our specs, we set out to answer the following questions:
- What are we building, and why?
- What should the final product achieve?
- By what means do we measure success?
To answer these questions, we include some or all of the following details based on the feature we’re considering.
Objective
Concisely capture what the feature accomplishes so that anyone can not only understand it but easily explain it to someone else. For example, when we built our Slack integration, our objective was to “Easily push messages from Slack to Productboard to quickly capture feedback from colleagues and customers.” It’s simple and straightforward.
You might also ask marketing or product marketing to help refine this message. Often, marketing gets involved at the end of the product development cycle when it’s time to launch a feature. However, getting those teams involved in the beginning to start thinking about messaging can get the marketing process started earlier and help you refine your vision for the product as well.
Measures of success — key results
Provide clear and measurable outcomes. Each goal should be easily quantifiable, such as “at least 80% of new users will use this feature more than once a week.” This is an excellent opportunity for collaborators to comment on whether those goals are feasible or if they should be higher, given the investment of resources. We use anywhere from 3 to 6, but you’ll need to determine the right amount for you.
Again for our Slack integration, we stated one of the goals as “X% of our customers would push at least Y messages from Slack a month.” This doesn’t only set a success metric, it also gives the team a sense of the scale for the feature. For example, if a feature you’re working on achieves a certain level of success and usage, is your system capable of handling it?
The “announcement”
Amazon is famous for writing press briefings for products at the beginning of a project to articulate the vision and to set the bar for how the product will be received. The announcement envisions the feature’s impact on customers and how they’ll use it. It will also get your teams excited about the work to be done.
For our Slack integration, we wrote, “We’ve heard from our customers how much they love to use Slack for team messaging and collaboration and how much valuable product feedback gets shared there. We have good news for you all! Slack + Productboard is finally here! Now you can easily share feedback from colleagues or customers directly to Productboard! Just set up the integration, and anyone in your team will be able to push relevant feedback straight to Productboard!”
Context
We call this the “big picture need” and it’s where you offer the broader context for the feature you’re building. Include assumptions, statistics, use-cases, and other types of evidence that will help make the feature more compelling. For our Slack integration, we wrote about how many users Slack has and how they’re an important channel for teams to communicate feedback.
Proper context provides clarity, especially for business stakeholders, around the importance of building a particular feature.
Detailed needs and solutions
It’s easy to get excited when coming up with a new solution because creating something is awesome. But what often happens is that, without any structure, you might end up creating amazing products or features that don’t connect to an actual need. In our eBook, C. Todd Lombardo talks about how the Amazon Fire Phone had some great technology at a competitive price but failed because it didn’t satisfy any specific need. That’s why it’s important to directly connect your solution to the customer’s needs.
Before writing down solution ideas, plainly describe each need related to the feature. Then involve everyone in creating and editing a list of solutions that may address that need. The point here isn’t to start with a definitive prescription for how to solve those needs, but to inspire a discussion to create the best solutions.
That’s why it’s also good to include a subsection for open questions where anyone can ask about the feature and needs. If you’re using Google Docs, this may very well be the area with a ton of comments from different folks. As the conversation wraps up, your spec will have a finalized set of solutions.
For our Slack integration, we had a need stated as “Push a threaded Slack conversation into Productboard.” The ensuing comments debated how to handle this for different use cases.
It’s also important to note which needs you’re not solving and why. These may be things saved for a later release or things you’ve decided you can’t solve. It’s helpful information when considering solutions, but it’s also important information for support organizations when they interface with customers.
Target audience details
As always, consider the target audience for the product. Who are you building this item for, and how will the customer use it in their everyday lives?
Mockups and design sketches
Why write when images will do? Including mockups and sketches is a great way to give your idea something tangible to review. Either drop in your ideas, or this can be where designers start adding in their ideas or inspiration from other products or projects.
For our Slack integration, we included the flow that users experienced when they integrated Slack to productboard via Zapier. We also included screenshots from Slack integrations with Asana and Zendesk.
Market research
In our eBook, Hiten Shah mentioned that he searches for existing reviews on similar or competing products when doing discovery. This and other types of research can be a useful endeavor when thinking about your solutions.
What have your customers said in the past about similar products? Have they made any special requests for new products like the one in mind?
What makes a good product spec?
The product spec isn’t just a document. It’s part of a broader process to flesh out ideas. One of the most powerful benefits of creating a product spec is that it allows you to apply critical thinking from the very beginning. It encourages communication between teams and drives accountability. Doing as much of this thinking up front helps reduce rework later in the process.
But what makes a product specification — or whatever kind of document you use — great is up to your team. For some, shorter one-pagers will work, and for others, longer documents with more precise information will work better. For example, the former may work better for smaller companies whereas the latter may work better for larger companies. Sit down with the stakeholders during product development to figure out what a robust collaborative process should look like and what kind of a supporting tool or document fits best in that process.
And don’t be afraid to change this as your organization and processes change.
You still need to prioritize and share your roadmap
After creating your product specs, you still need to prioritize the work against many of the initiatives you have planned. You’ll need to create a product roadmap to rally the entire company of what you plan to build. Our product management software helps you build the right products for your customers.
