On empowering your team with product documentation

Teju Adeyinka
7 min readSep 26, 2023

--

While the naming and format may differ across companies, most software teams rely on some version of a product requirements document (PRD) to drive product execution. These documents are an essential part of the product development process that helps teams create shared knowledge and visibility, align on the ‘definition of done’, and generate momentum before building starts.

I have worked with teams that use elaborate multi-page Product Requirement Documents (PRDs) covering every scenario, as well as teams that use shorter documents like the product pitch popularized by Basecamp. There’s no one way to create a good PRD, so this article isn’t focused on structure and semantics, but rather on principles to ensure that your documentation empowers your team to build the best product possible regardless of the format.

Based on the lessons I’ve learned from working with others, mistakes I’ve made, and areas where I have found success, here are some key principles for creating effective product documentation:

Clarify your own thinking with the document

It’s important to think of the PRD as a thinking document rather than a checklist of tasks for your engineering and design team to work on. Writing is an excellent tool for clarifying your thinking about a subject, and when done right, your PRD should help do the same for your product or feature.

Most PRDs start with some form of a problem statement or product context; rather than glossing over a pre-written problem statement, use the process of writing that section to double-check the assumptions you’re making, including any widely held beliefs about the problem or solution within your team. Pull the data, user research, and any broader strategy documents that can help validate that you’re thinking about the problem and your goals correctly.

In a perfect world, we have all the data to back up our assumptions and only build things that we have strong convictions about, but that simply isn’t the case in reality. We work with imperfect information and sometimes build things based on bets that others are making. It’s important to call out these assumptions and be honest about why you’re doing what you’re doing, the potential risks, and the upside. Additionally, you should include links to any strategy documents and data behind your thinking for further reading.

Using the PRD to clarify your thinking should also extend to the solution and prioritization process. Think about how the solutions you’re exploring tie into the problems you’ve defined, and use it to identify risks and possible mitigation.

Be clear on your goals

It’s important to frame the effort in light of the goals you want to achieve. Beyond helping your team measure success, having clear goals also helps to set common ground and empowers team members to hold each other, including the PM, accountable during execution. I’ve had teammates use the goals that we’ve set to argue for or against certain decisions during execution.

Beyond the North Star and other product-specific metrics, it’s also critical to capture “meta” goals that are important to your team/company such as getting the data you need to (in)validate a hypothesis or learning about how your customers will use a feature.

Overall, your goals should drive the approach to solving the problem including the level of polish required, data instrumentation, trade-offs to be made, etc. For example, if “learning if our users will pay for a new upgrade” is a goal for a feature, then that drives the trade-offs towards prioritizing the payment flows over some other parts of the interface.

Having clear goals also helps to remind the team of the mission, and can act as motivation when day-to-day execution starts to feel like drudgery. It provides a focus for the team and is an easy way to determine when you’re going down an unnecessary rabbit hole during execution.

Document principles

Resist the urge to create a simple checklist of items. I find this to be fairly challenging because oftentimes, you already have a list of decisions that have been made and features to include. However, especially for larger projects, it’s important to take a step back and document how you are making the decisions on what to prioritize and include.

When working on a feature that has a set of similar rules, it’s important to include high-level rules to help your team be incisive. For example, if certain UI components should only be shown in some cases but not others, a good exercise to include in the PRD is; “For a given state, how do we know if to display a, b, or c?”. Documenting these principles empowers your team to make their own decisions as they work on their tasks. Of course, they might still need specific input, but having clear principles moves you from providing all the answers to having your team contribute their perspective and expertise and drive even better decision-making.

Get feedback — early and often

When working with a (cross-functional) team, naturally, people will have varying contexts, assumptions, opinions, levels of expertise, etc. that impact the eventual output of the product. Getting everyone on the same page about the problem as early as possible, as well as continuously through execution can and will save you a lot of headaches. If you’ve been a PM for long enough, you’re either a communications wizard 🪄 or you’ve seen people act unaware of information that you were 100% sure that they had. Eventually, you realize that the buck stops at you to overcommunicate and ensure that the right eyes and ears are on your documents.

Figure out who is most likely to have strong opinions about the product/approach, and seek out their feedback. Don’t assume that everyone has read the document — if you haven’t seen feedback from a particular person whose input you need, call out the specific piece that you need them to pay attention to. For instance, if you’re assuming that a piece of data will be available, tag the responsible/knowledgeable party.

In my experience, the best approach is one that involves some active participation and acknowledgment. One option is to arrange a workshop such as a customer journey mapping session where everyone can share perspectives and ideas as you map out the user flow. This will make your document an extension of that session, and participants will be more likely to review it. Alternatively, you may hold a review meeting with all stakeholders, request participants to provide feedback in advance, and then discuss those comments at the meeting.

Pictures (or diagrams) are worth a thousand bullet points

I learned this from one of the engineers on my team who creates diagrams for lunch. Where possible, augment your writing with pictures and diagrams to make it easy for others to visualize what you’re communicating. Use user and process flow diagrams, wireframes, button mockups — whatever brings your thoughts to life.

Using pictures creates a stronger definition of done. Sometimes, working with others can feel like a game of Chinese whisperers — “he said she said”, and “I thought you said” with each person having a different understanding of what’s expected in the end. One of the best ways to avoid running into these challenges is to commit to user flows in diagram form. It makes the information a lot easier to parse and helps the team to clearly understand the expectations.

Beyond readability, I’ve also found that it helps with identifying dependencies and empowers the team to critically review the flow. When the other subject matter experts on the team have a flow diagram to reference, they can easily identify and poke holes, find potential roadblocks and optimizations, and point out if there are concerns about delivering on them.

Additionally, you can use “stories” and real-life customer scenarios to describe the future state. Show how the future is different from today not just in terms of a feature list, but also what the user is powered to do and how they’re able to do so with the product/feature.

Show (and tell) how the future differs from today, and how the solution empowers that.

Don’t forget non-functional features

Everyone knows how important it is to cover the functional features for your users. But it’s just as essential to cover any non-functional requirements, which your end users may not directly interact with, but are critical to the success of your product. These can range from non-functional engineering requirements such as scale, and speed, to internal tools required for observability, revenue recognition, support processes, event tracking etc.

As always, these non-functional features should stem from your goals for the product. For instance, if one of your goals is to hit a particular dollar milestone, then outside of the core product features that get you there, you also need to be able to measure your progress toward the milestone — so you need to include features such as the data pipelines that make it possible for you create any internal dashboards to measure the goal.

Keep your PRD up-to-date

A PRD is a living document that should evolve as your knowledge of the problem, features, feasibility, timelines, etc. During the product development process, as amorphous ideas begin to take shape, assumptions get (in)validated, and wireframes start to become higher-fidelity designs, the document should also be updated to reflect this new information.

This way, it remains the source of truth for other stakeholders in the company to understand the product and acts as a reference point for creating other product and support documentation.

There are a lot of other things to keep in mind, but these are just a few that I hope you’ll find helpful. Again, while the template you use isn’t the most critical thing, here are two that will come in handy if you need help figuring out a structure that works:

May your launches be successful, and all the right graphs go up and to the right 📈!

--

--