It’s afternoon, a legacy feature behaves inappropriately, and you finally figure out that the cause of the bug lies in the single line of code. You perform the git blame, only to realize that this change is coming from a three-year-old Pull Request. And guess what, its title is Update utils.js, and its body…is empty.

It happened to all of us.

Throughout my developer career, there have been numerous occasions where I needed to dig through the company history, trying to find an explanation of why this particular piece of functionality was implemented. While a Pull Request may seem to be just a tool used during code reviews, it should be regarded as a document describing what, why, and how certain changes were introduced.

When I write a Pull Request today, I try to think of my future self (or some outsider) who might stumble upon this PR by searching for information on Google.

Based on my experience, creating a decent “organic documentation” involves several steps which, I think, everyone should follow:

1. Avoid default Pull Requests’ titles.

No need to use something like Fix a bug or Update FILE.md. Instead, try to describe the essence of your change in such a manner that would make a perfect sense to someone who has never seen this Pull Request before.

2. Tell the “why”, not just the “what”.

The diff reveals what exactly has changed. However, the PR body should explain why this needs to be done. What problem is being addressed here? What options did you evaluate? Are there any risks associated with implementing the proposed solution? Don’t forget to provide a short summary on top.

3. Leave traces.

Mention any related tracking issues (and close them, which is a nice bonus) and cross-reference with other Pull Requests. If you expect a response from a specific team, don’t forget to notify it in advance by mentioning it. In this case, please, add the reasoning behind this mention and clarify whether this team needs to do something.

4. Demonstrate, not just describe.

Suppose you’ve just updated UI design and want to inform the reviewer of this change. Please, add a corresponding screenshot or a GIF in the description. No need to ask reviewers to set up a development environment on their own in order to verify a change in color.

5. Pre-review yourself.

Before you request a review from a colleague, make sure to carefully review your own diff. Mark some lines with comments to provide additional context. This could be a great place to ask a bunch of silly questions which you may ask in the discussion.

6. Be discrete.

Don’t include all your changes to a single PR. Try to create several smaller ones with separate scopes and clean diffs. This is the best approach both for reviewing and for future discovery of these changes.

Obviously, it takes more time to write an extensive Pull Request instead of performing a fast one-off thing. But please, remember how difficult it is to maintain static documents on Confluence. Trust me, it’s worth the effort, both for you and others.

Want to know even more tips? Here’s how to write the perfect pull request ↗ on GitHub Blog.