How to Write Good Product Docs

Documentation gets a bad rap. It’s a dirty word — especially at tech startups where it seems to go against every grain in our rebellious, “move fast and break things” brains. Documentation, we say to ourselves, is for historians. Everyone on my team is already aligned, we tell ourselves, so why waste time on writing it down.

Wrong. Docs are sexy. I would go so far as to say that keen documentation is a core competency of effective product management. That’s right. As much as we PMs like to think of ourselves as “CEOs of the product”, a large part of being successful is embracing our role as “glorified note takers”.

Good doc / bad doc

A lot of PMs are resistant to writing docs, because they’ve been burned before. The docs they know are lifeless walls of text that sit around and collect dust. It’s easy to see why the idea of spending the time to write that kind of doc is unappealing. Not all docs have to be this way.

A good doc is written to be read. It’s acutely concise. A good doc is well formatted, and can be read and understood in three minutes, by anyone in the organization. It avoids jargon, and either provides business-level perspective, or links to it. A good doc takes the time to outline non-objectives and risky assumptions. It challenges the reader, and pulls out underlying disagreements for discussion.

A bad doc is written to be written – a checkbox on someone’s todo list. It uses sprawling sentences of vaguely agreeable sentiments, and sloppy formatting, to dissuade readers from engaging with its contents. A bad doc is written to protect the writer from dissent, and is a waste of everyone’s time.

The power of a good doc

If your organization has more than two other people working together, creating a culture of writing good docs is probably worth your time. There are two reasons: (1) good docs are a lightweight way to elevate decision quality, and (2) good docs allow product teams to scale.

Good docs elevate decision quality

Most PMs are optimists – they have an idea, they get excited, and then they execute. Passion is great, and execution feels productive, but it’s incredibly wasteful when the initial decision was not made with enough intentionality.

Kicking off off a project with good doc template forces us to step back and be intentional. Even the biggest rockstar PM on your team sometimes forgets to specify non-objectives before kicking off a design cycle, sending their designer off on a goose chase. It’s the same idea behind Checklist Manifesto – why force yourself to remember a processes that could be systematized?

Also, knowing that your written words will be read by others in the organization raises the bar. As the writer, knowing that you won’t be in the room when your words are interpreted by your superiors and co-workers, forces you to uncrumple your thoughts and intuitions in a highly productive way.

Good docs allow product teams to scale

People think very differently. It’s amazing how easy it is for a group of people to leave a meeting thinking they’re in agreement, only to discover (later) a misalignment that slows execution and erodes trust.

A well-written doc is like creating a hundred (super eloquent) copies of yourself. The combinatorics of 3+ stakeholders spins out of control very quickly, and even the most extroverted PM can’t expect to insert themselves into every possible conversation to make sure folks all have the same assumptions in mind.

Good leaders repeat themselves, and a good doc supercharges that ability. Good docs also enable efficient asynchronous communication, killing unnecessary meetings and freeing people’s time. Reading a good doc takes three minutes, and allows the reader to choose whether to invest further by commenting, or to move on to other work. Discussions within docs are contextual, efficient, and centralized. Discussions in meetings tend to be inefficient for everyone except the asker and responder.

How to write good docs, and create a culture where it’s the norm

Writing good docs is hard, and there’s no one-right-answer. Below is an overview of how we tackle the challenge at Amplitude.

Template for the “Product one-pager” doc we we use at Amplitude. This doc aims to enforce product problem definition clarity, before a design cycle is kicked off.

Page limits enforce clarity. Writing a good doc should be hard. Long, winding, sentences are generally reflection of a lack of clarity. If the communication can’t effectively fit on one page, it’s a sign that the PM should probably go break down the problem some more.

Templates save time. It’s a lot less work to delete a section in a template, than it is to remember to add one. It’s not condescending, it’s efficient. Having simple sections that remind the writer to start with the high-level context, and to be explicit about metrics or risky assumptions, facilitate clearer writing and decision hierarchy.

Formatting elevates quality. It’s like the broken windows theory where people are more likely to litter in a neighborhood with broken windows. Docs are the same way — a sloppily formatted doc makes the writer more likely to wing it. Take the time to create a template with nicely formatted sections, tables, and doc headers. It’s a one-time investment that pays dividends.

Comment, comment, comment. There’s no better way to de-motivate your team from writing good docs than to not comment on them. Comments don’t have to be particularly insightful, they just need to demonstrate engagement, and to set an example. Ideally comments are delivered in a digital way so that others in the organization can asynchronously benefit from the discussion, but I’ve also seen the print-out-and-put-on-your-stakeholder’s-desks method work.

Doc types should scale according to your organization’s needs. As more stakeholders become involved in the product development process, you will need to split out communication into more docs (especially if you want to keep the one-page ‘conciseness’ requirement). Below is an overview of the docs that are currently part of Amplitude’s product development process.

Docs that are currently part of Amplitude’s product development process.

Docs docs docs. If you’re part of a similarly doc-obsessed product team, we’d love to hear from you. If you have a better alternative for enforcing product decision quality and scalability, we’d also love to hear from you.