Write pull requests that invite reviews
3 ways comms skills can make you a better dev — Part I
Don’t bury the lead.
I picked up this journalism mantra as a communications major, and it’s stuck with me as I moved from writing press releases to pull requests.
What’s the lead? And what does it have to do with pull requests?
If you examine news stories, you’ll find they commonly follow a structure called the inverted pyramid. They start with a lead paragraph that contains the most important and newsworthy information — the base of the pyramid — followed by supporting paragraphs with less essential details.
The stories are written this way to help the reader quickly understand the gist of the overall article and what types of details will follow the intro. If the reader only makes it through the first paragraph, they’ll still have learned key details like the who, what, where, when, and why.
Applying the inverted pyramid style to the body of a pull request can similarly benefit your teammates during code review.
I can categorize most PR bodies I’ve written or read into the following buckets:
- Too much info
- Too little info
- Just enough info
I’ve found that the inverted pyramid makes it easier to write a PR body with just enough info.
The body opens with a clear, concise description of the problem and solution followed by supporting details like:
- The reasoning behind the solution
- Relevant business logic
- Areas where you especially want feedback
- QA steps
- Links to related tickets, requirement docs, etc.
(Bullet points can also be a great tool for making key details easy to find)
Some teams use templates for PR bodies, but if you have freedom in any of the sections and find yourself writing a paragraph or more, think about the inverted pyramid. Its formulaic nature speeds up the writing process while helping you get your point across.
Pick up more communication tips for devs:
- Intro: 3 ways comms skills can make you a better developer
- Part I: Write pull requests that invite reviews
- Part II: Think like a copy editor to move faster as a developer
- Part III: A simple public speaking template for developers
