What/Why/Notes

I want to share something that’s been useful to me in writing pull request descriptions. It has crystallized something I’ve been reaching toward for a while. It has helped me write better pull request descriptions, and others have taken up the idea and have found it has helped them too. It’s called What/Why/Notes.

What is it? #

Each pull request description gets three sections: What, Why, and Notes.

The “What” section succinctly describes what the pull request is about, providing as much context as the reviewer and future puzzled engineers are likely to need to locate this change in their own mental model of the world.

The “Why” explains why you are doing this at all, why it’s a good idea, and optionally why you are doing it this way rather than a more obvious way. It is the most important section.

The “Notes” section is for everything else. I mostly write it in bullet point, but sometimes wander into paragraphs. Here, I mention things where I particularly want reviewer attention, talk about approaches not taken, link to other relevant stuff, explain why I’ve left some things out for future PRs, and so forth.

Why do it? #

The most important section is the “Why” section. Most engineers can figure out the “what” if they look at the code for long enough even if they don’t have context, but they cannot know what you actually meant to do or what you were trying to achieve unless you actually tell them.

This matters a lot at review time. When the reviewer knows the “what”, they can check that the code does what you say it does, and they can check that the tests check that the code does what you say it does. If the reviewer does not know the “why”, they cannot help you determine whether you have achieved what matters, because you haven’t told them what matters.

The “why” matters more once the code is merged. Inevitably, someone will look at the code and wonder why it is there at all. If that’s not written down somewhere, they won’t be able to figure it out. I mean, they could ask you, but you are probably asleep, or in a meeting, or have been promoted to a level that makes them quake with terror at the thought of speaking to you. Best to write it down.

Having a freeform field at the end makes space for all the other bits and pieces that you might want to share, without trying to force a structure that doesn’t really exist.

Other things #

Why “why” is not first #

Originally I tried to make “why” the first section, per Simon Sinek’s advice to Start With Why. It doesn’t work though. You can’t say why something is a good idea if no one knows what the “something” is. If you try to start with why and be strict about it, you end up with contorted sentences and paragraphs. In practice, the best way to “start with why” is to have a couple of short sentences saying “what”.

Concrete example #

Here’s a description from a recent pull request I made at work:

## What

Remove all `import` and `moved` blocks from Terraform configs across
the repo.

## Why

These blocks have all been applied and are now just noise. Removing them
makes the configs easier to read and maintain.

## Notes

This touches 22 files across `REDACTED-1`, `REDACTED-2`, `REDACTED-3/*`,
`REDACTED-4`, and `REDACTED-5`.
Every Terraform plan should be a no-op since these blocks were already
applied, but there are a lot of state files involved. Happy to break
this into smaller PRs per directory or environment if we'd rather not
big-bang it.

AI #

Naturally, writing all this stuff down helps agentic coders as much as it helps human coders—perhaps more so, as a human reader is likely to have personal history with the system and institutional knowledge, whereas an AI agent only knows what it has been explicitly told.

You can also use AI to help you write pull request descriptions using What/Why/Notes. I have this section in my CLAUDE.md to help me:

## Pull Requests
- Keep PR descriptions short and clear. Use three separate headings:
What, Why, Notes. Avoid bullet points for What and Why. Notes should
highlight non-obvious implications, risks, trade-offs, and things
reviewers should specifically watch for that aren't apparent from
reading the code diff. Avoid stating obvious facts or repeating
What/Why.

Others have copied it and said it has helped them. Please feel free to do the same.

Looser forms #

You’ve probably noticed that this post is written in a What/Why/Notes structure but with different wording in the headings. That’s great! We’re social creatures and the ways we communicate with each other should vary based on our relationships, context, levels of trust, shared culture, and many other things.

When I’m writing design docs or proposals, I make sure that “What” is addressed in the first couple of sentences and that “Why” forms the next paragraph, regardless of where the headings are. If someone stops reading the doc there, then we’re in a great place to have a useful conversation, and often they feel informed enough to make a decision. The structure is a tool for thinking, not a template.

Acknowledgements #

Thanks to Jason Meridth for encouraging me to write this up, Phil Roche whose internal “Share the Why” helped my thinking a lot, and Chainguard for providing a supportive and stimulating work environment.