In Defense of Product Documentation



A decade ago when I started my career in product management, most tech shops gave this role an ambiguous label like consultant or analyst. At the time, besides being a source of an existential crisis my job description had two other problems: I couldn’t explain it to my mother, and it involved authoring specifications – the kind that made its author and readers want to die!

Now, most tech teams either include a product manager or are wondering if they need to. And while my mom still doesn’t get what I do, she is generally pleased that my title says “manager” of something. Also the artifacts that product managers need to produce have evolved to match the personality of the creative people who are typically attracted to this profession. (More on this in a forthcoming post.)

Still, on many days, I have to sit at my desk for hours.

Burn That Burn Notice

So please hold the burn notice on product managers, like me, who believe in the discipline of documentation. Surely they too got the memo that outlined the Agile Manifesto, announcing that they must value “working software over comprehensive documentation.” On occasions, however, to produce working software, product managers have to create artifacts that don’t fit on the back of an envelope. Perhaps your project or aspects of it are suited for one approach or the other or something in the middle.

I offer a framework to help facilitate the decision that is best suited for your environment.

Scenario: Skip It!

“If you can’t feed a team with two pizzas, it’s too large,” said Jeff Bezos, speaking about a principle for organizing task forces at Amazon. Your crew also ascribes to this philosophy of the “two pizza team”; your team is five to seven people strong, all players: product managers, user experience experts, engineers, et al, are co-located, and each of you toil away in the same time zone. The power to make all decisions is bestowed on your pod. Finally, if you launched a product that was good-ish, then there would be no catastrophic ramifications of getting a few things wrong. In that case, dust off your Pictionary supplies – whiteboards, post-its, markers, notecards, etc. – because they will suffice to efficiently design and deliver stuff that works.

Scenario: Budget Time For Detailed Documentation.

But imagine that your team is laboring on software that assists users with investment decisions or managing their chronic illnesses; and that your crew needs to collaborate with experts and contractors who are scattered in different parts of the world. Further, let’s suppose, that your industry is highly regulated. I argue that in this situation the product team would be hard pressed for credible reasons to avoid the grunt work. To efficiently support a distributed (not collocated) team, product managers would have to find disciplined and predictable ways to share their knowledge.

In addition to how they communicate, they also have to think about what they produce. Product managers would have to go beyond jotting down a handful of features and user stories and sketching some wireframes.

They’d have to complement their high level ideas with outputs that convey the complexity of the product.

Why is that?

To improve product quality: With complicated solutions, it’s harder to preempt edge cases i.e. how things might go wrong when a user interacts with a product or how the product will cope with changes to underlying assumptions, say regulation, for instance. The sooner in the cycle of product development the team uncovers these scenarios, the better they are equipped to architect for them.

While PMs can’t eliminate the risk and cost of missing something upfront they can reduce it by looking at the human and system interactions through different lenses. Blueprints, for instance, push us to study the impact of touch points with users on our internal teams and systems. Other examples include plotting the current and future state journey maps, and writing a substantial number of user stories with traceability to features.

To efficiently scale insights: Among other activities, product managers pour hours into cultivating a deep understanding of the motivations of users. And while PM’s are considered the “voice of the customers”, the success of an offering hinges on decisions made by individuals from engineering, marketing, customer service, sales and so on. They too must gain empathy for the users, empowering them to make informed choices in their area of expertise.

The question, then, is how to accelerate this learning process for those outside the product team? Dragging them to all your user interviews, for instance, is inefficient. Disappearing into the product-people-cone-of-silence to emerge weeks later to announce your brilliant outcome is the other extreme. For instance, leading up to the day when you reveal User Personas, could you publish a few write-ups or audio snippets, videos of memorable and surprising conversations from the user interviews?

To build reusable assetsIn the end when the product managers slog at their desk for an hour or so each day, everyone benefits. It pays off over time because the organization accumulates reusable assets, which become a resource that can be mined for fresh angles, allowing teams to pivot on a short notice. At the end of the project, product managers, too, can walk away with a portfolio that showcases their contribution.

So people can go on a vacation: Yes, product managers are the guardian of the customer’s needs. It spells trouble if a team can function only while their product manager is in the building.

To set aside time for these activities, is not a matter of personal choice since it costs the company time and money. I use the below visual to aid the decision-making process with my peers and colleagues. I invite you try it or craft your own. My message is for teams to make an informed choice to set off in one direction or the other.


Learn More about Product Management at GA