Show HN: Guide to better pull requests and code review
github.com
I listed all the advice I give about Pull Requests and Code Review into a short (37 pages) and free guide, with real-life examples and actionable insights.
github.com
First: kudos on writing this down and sharing it under a permissive license. It's great to contribute like that, and it takes effort to produce something and generosity to license it as CC.
Feedback: not much, I liked it. But I want to be as useful as possible so here are my thoughts.
Reading, I was surprised to jump straight in to "Create your PR before the code is ready for review", because somehow I expected more of a soft landing. But I realised: it's a guide for those who know PRs and know why to use PRs, so why not jump in? Still, the intro could contain a final sentence like: "This is not a guide to encourage you to use pull requests. It assumes you already use them and know their usage thoroughly. It is a guide of practical advice how best to use pull requests and achieve the best from code review. Let's jump right in."
Also, on code review, one technique I find useful which I didn't see is asking questions. You did suggest to ask for clarifications, but I think this is subtly different. Sometimes, you review code you don't know: it's ok to admit ignorance and say, "I'm unfamiliar with this library, but the method name implies... are you sure that...?" Or, you can see someone made a decision, and it can be perfectly fine, but it can be useful to ask about it in order to get it documented.
A good code review is also a form of documentation, and can be referred back to later.