To those of the agile persuasion, a product requirements document may sound like a bit of a relic — a straight-jacket that doesn’t capture the fluid push and pull that actually happens when building a new feature or retooling an interface.
But the name is something of a misnomer, said Javid Muhammedali, a former McKinsey & Company consultant and head of product at the software recruiting company Avrio AI, who led the search and software business at Monster.com in its heady early days.
“I look at it more as, ‘How do you build passion and enthusiasm and leadership?’ Because a product manager is one of the only roles in a company where you have extreme influence, without extreme authority,” Muhammedali said.
“Product manager is one of the only roles in a company where you have extreme influence, without extreme authority.”
The way you rally engineering and sales teams behind you, he told me, is by thinking of the product requirements document as a press release with enough “sizzle” to convince sales reps to hop out of bed in the morning and make phone calls. “You want it to be punchy, you want it to be accurate, but you also want it to sell,” he said.
Of course, a product requirements document is much more than a marketing vehicle. Troy Bolus, the founder of the business analytics tool OmniPanel and the former head of product at the New York-based dining app company Seated, describes a requirements document as a “functionality and logic tool” that can save project time and development costs by clarifying engineers’ roles and articulating to stakeholders “what a feature will do and how it will work.”
It’s short: Most experts agree the document should fit within a page or two — in agile’s early days, it was often written on an actual index card. Product leaders, including Muhammedali, will tell you it should cover the scope of a release shippable after a single sprint cycle.
But the format is less important than the function, said Brittany Skolovy, chief growth officer at the Canada-based children’s messaging platform Kinzoo. She conceives of a product requirements document as a living, co-created set of guidelines for “what we want to build and why it will solve the [user’s] problem.”
We asked product leaders to share insights for writing clear — dare we say, exciting? — product requirements documents.
How to Write a Great Product Requirements Document
- Decide whether the feature is worth your time.
- Choose a template matching your team's working style.
- Give sufficient direction, but don’t overwhelm your team with requirements.
- Flag corner cases that may lead to unexpected behaviors.
- Focus on the message, not the medium.
- Involve stakeholders early so they can raise concerns.
- Think about your requirements doc as a press release — will people be excited to use what you're building?
1. Decide Whether the Feature Is Worth Your Time
Before writing a requirements document, it’s good practice to identify what releases are actually worth building and shipping. In making this assessment, the first question to ask, Muhammedali said, is whether the release has enough differentiation from competitors to draw customers’ attention. When BlackBerry released a single-click feature to approve workflows from a mobile device, it made headlines because no one else had done it.
“It’s not exciting to you, I’m sure. But back in the day, people were amazed that such a thing was even possible,” Muhammedali said.
The second criterion is whether the release will deliver value over time, which is “what the Walmarts and the Amazons of the world have done,” Muhammedali said. “We can do this at a cheaper cost than anybody else can and we’re going to beat the market that way.”
The third factor is whether the release can improve operational efficiency. “You might build a feature that nobody ever sees, that nobody ever uses. But somebody in your company has to do ten times less work because now you’ve automated this thing.”
Rarely does a feature meet all three criteria, Muhammedali said, but if you’re going to commit to the time and resource investment to add it to the release cycle, it should fulfill at least two.
Questions to Ask Before Developing a Feature
- Does it differentiate you from competitors?
- Will it deliver value over time?
- Will it improve operational efficiency?
2. Choose a Template Matching Your Team’s Working Style
Selecting a format and framework that serves the needs of your team’s working style can help invite participation and build consensus around key ideas.
Skolovy uses the “Write the Pitch” chapter of Basecamp’s guide Shape Up: Stop Running in Circles and Ship Work that Matters as the basis for a one-page document organized in a problem-solution structure. The collaborative approach works well for the early stage start-up. A short problem description explains, “Who are we building this for” and, “What are we trying to accomplish?” It includes high-level research findings from analytics tools, customer interviews and customer reviews.
This is followed by an “appetite” subsection, which outlines how the amount of time you want to spend on the project may constrain the solution. Is this a week-long project? A six-week project? What value will it bring to the business? A final piece of the problem description, modeled after the late Harvard University business professor Clayton Christensen’s Jobs to Be Done theory, probes the user’s situation, motivation and desired outcome. It uses the familiar user script, “When I” (am in this situation) “I want to” (explain the user motivation) “so I can” (what is the desired outcome?).
“A lot of it is setting context for the engineers, both in terms of ‘Why are we doing this immediate feature?’ and also ‘How does it fit into the longer-term vision of your team?’”
The solutions portion of the document describes the feature to be built, along with the evaluation metric or metrics, links to rough sketches and questions to be answered. It concludes with what Skolovy calls “rabbit holes” — use cases that lie outside the scope of the product requirements document, but may be revisited in future releases.
“It forces you to make sure you aren’t jumping ahead and you’ve covered all your bases,” Skolovy said. “And it serves as a really fantastic jumping-off point for deeper discussion. This happens before we’ve put anything into Jira, before a designer has started working on a concept. It becomes something that we all contribute to, discuss, comment on, and share.”
Another popular framework is a model by Marty Cagan, a partner at Silicon Valley Product Group. Jerry Cao, writing for Medium, describes it as a four-part document “defining purpose, describing features, setting release criteria, sketching rough timing.” The goal, Cao explains, is for a product manager to describe the “What,” not the “How,” leaving flexibility for engineering and design teams to arrive at solutions on their own.
Ben Staples, a senior product manager at Nordstrom, said he applies a framework similar to Cagan’s when he writes product requirements documents for product pages on the company’s website. Grooming sessions involving engineers and members of the SEO team help clarify the rationale for building particular features and explain where they sit in the long-term roadmap. Providing a view of the future allows the architecture to be designed with enough flexibility to accommodate anticipated features and new customers.
“A lot of it is setting context for the engineers, both in terms of ‘Why are we doing this immediate feature?’ and also ‘How does it fit into the longer-term vision of your team?’” Staples said. “We want to make sure we’re aligned on the done criteria. What does this feature look like when it’s done as a whole, so we’re as aligned as possible on the minimum viable product we’re willing to go out with.”
3. Follow the Goldilocks Rule
Keeping product requirements concise — a small slice of work nested within a larger development framework — helps keep a release focused and manageable.
At the online clothing company Trunk Club, now a part of Nordstrom, Staples previously led the product development of the native app across iOS and Android devices. An early version of the Trunk Club app opened directly to a messaging interface with an apparel stylist. Over time, this evolved into a more conventional homepage where a customer could order a new “trunk” of clothes, or travel to other places in the app. Tightly scripted product requirements documents were crucial in preventing feature creep.
“The document should be kept under two pages, with appendices and links that allow for further expression of an idea in wireframes and prototypes.”
“There were so many different features we could layer on and surface to the customer,” Staples said. “But the team really worked nicely to strip out a lot of those features and just go live with the homepage to see how it would resonate with the customers.”
The Goldilocks Rule — the idea that when developing product requirements (or assignments of any kind) you should give just enough direction to team members to motivate them, without overloading them with specifications and rules — is a lesson he said worked well in this instance and is widely applicable.
“You don’t want to take up too much of your time in creating this avalanche of requirements and documentation, but you also want to give your engineers and stakeholders the right amount of information,” Staples said. “I used to work for two former Amazon managers who said, ‘How do we get this to a point that we can give a document to someone and not have to walk them through it, and instead, they can read it and fully understand the concept?’”
The document should be kept under two pages, Staples said, with appendices and links that allow for further expression of an idea in wireframes and prototypes.
4. Consider Corner Cases
But shorter doesn’t mean easier. The French mathematician and philosopher Blaise Pascal is credited with the earliest use of the phrase, “If I had more time, I would have written a shorter letter,” which appeared in Lettres Provinciales in 1657. The same idea (if we can swap out the letter for a software doc) applies to product requirements documents: a concise, informative one-pager is often the result of considerable time spent pre-writing and doing background research.
Take Bolus’ process at OmniPanel. For new user-facing features, he creates rough mock-ups of user flows in Adobe Illustrator. For back-end billing systems or notification frameworks, he writes flowcharts. These are sent to the design team to be developed into more formal plans. On receiving the proofs, he then annotates a short list of “empty states” ”or “corner cases” that defy global coding rules.
“There are often assumptions [built into product requirements], and I think the ambition of product managers should be to surface and understand as many of those as possible, as early as possible.”
An unusually long name entered into a text field, for example, may require a second line to handle overflow characters. Bolus doesn’t write the code for such scenarios, but he flags them for engineers to address.
Having a place to preserve corner cases for future reference — like a strong brain or a Google doc — is a good way to increase development speed over time, Bolus said. “The other thing I would advise is that there are often assumptions [built into product requirements], and I think the ambition of product managers should be to surface and understand as many of those as possible, as early as possible.”
This requires step-by-step, tactical thinking and a fair amount of engineering knowledge: “One of the features we’re releasing is a search feature that returns customer support tickets from a database integration in third-party tools,” Bolus explained.
“So when writing the functionality for something like that, you break it down,” he continued. “Are we searching database parameters by name, by a value? What is actually returned when we perform that search? Are we returning the database item? Are we returning a support ticket instance? Are we returning a user and their associated information? And then finally, what is the ordering of those items that are returned?”
5. Focus on the Message, Not the Medium
Product requirements documents can be created as short narratives in Google Docs or represented through a software tool like Zeppelin or Figma that provides options to write comments directly into a design.
While agile teams may not use the term “product requirements document” or craft their ideas in succinct physical documents, that doesn’t mean the thought exercise is unimportant.
“Agile has a different way of thinking about requirements,” said Travis James Fell, a product manager at the virtual smartphone company Hypori. “In agile, the requirement is the shared understanding of the user problem between the delivery team and the user.”
“We still do use artifacts like wireframes, tables, data flow diagrams to help tease out what the user’s problem is,” Fell continued. “So there is a need for these types of documents. But while they’re important, it’s been my experience that the agile approach gets the requirements definition a lot closer to the actual development of code.”
6. Invite Stakeholders
External stakeholders should be invited into the planning process early, especially if a release is likely to impact their business. While Staples does most of the writing for the product requirements documents that steer new features on Nordstrom’s product pages, the written product is the result of a broad partnership of stakeholders who have a vested interest in the outcome. The same was true when he was working on the Trunk Club team.
“So the changes we were making,” he explained, “would have big implications for both the stylists themselves, but also all the infrastructure that deals with managing stylists, whether it’s the tools that they use, or the communication methods that we have to interact with them. Because the features we were planning to introduce would change their metrics a lot, we needed to make sure to loop them in,” he said.
“If I’m a salesperson, and not a technical person, I’m a user of Salesforce, right? Does the headline make me want to get out of bed and start making phone calls?”
At Nordstrom, product requirements documents “ladder back up to stakeholder management but in a different flavor,” he said, “where you’ve got a physical store presence and you want to make sure that you’re considering things like sale periods, such as the Nordstrom anniversary sale going on both in stores and online.”
Oftentimes, key stakeholders are the engineers and developers assigned to the project. “I’m making sure to have meet and greets with my engineers to understand what’s valuable to them as they’re building out these features,” Staples said. “What’s working right now? And what would they like to change?”
He continued: “You never want to want to go to an engineer or designer and be like, ‘Hey, I saw this, and let’s do it.’ Rather, you really need to present [product requirements documents] as ‘What’s the customer problem?’ and ‘What am I trying to solve for the customer?’”
7. Write a ‘Working Backwards’ Press Release
Muhammedali said his best piece of advice is the one he shared at the outset: Think of a product requirements document as a press release to be sent to news outlets at the time the release is shipped. Does it have a daring lede? Is it easy to digest in a headline? Would it be something a news outlet might pick up because it is genuinely meaningful in people’s lives?
“If I’m a salesperson and not a technical person, I’m a user of Salesforce, right? Does the headline make me want to get out of bed and start making phone calls? Is it important and useful? Does it give me another reason to call the customer?” Muhammedali said.
