技术写作与文档2020github.blog
如何写出完美的 Pull Request
How to write the perfect pull request (2015)
导读
这篇 2015 年 GitHub 官方博客文章讲的是：如何写好一个 pull request（PR）的描述与沟通过程。它把「写 PR」当作一种写作练习：既要让评审者快速理解改了什么、为什么改，也要在评论里照顾语气和协作关系。对写作者来说，这是一份关于「向真实读者解释自己的改动」的极佳范例，也提醒我们：技术写作同样需要为读者设计。
可以直接用的写作要点
- 01
先讲「为什么」再讲「改了什么」：让评审者不必从 diff 里反推你的意图。
- 02
控制体量与范围：一次 PR 只解决一个问题，读者的注意力是有限资源。
- 03
语气是可以被设计的：与其堆 emoji 或感叹号，不如直接把友好写进措辞里。
- 04
反馈时在「提问」和「直说」之间做选择，取决于团队默契，但都要具体、对事不对人。
HN 评论精选
表达友好不必依赖 emoji，措辞和标点本身就能传递语气。
用 emoji 来表明语气。比较一下「✨✨ Looks good 👍✨✨」和「Looks good.」，差别多大。或者，你也可以直接写「Looks great!」。感叹号才是最早的 emoji。
airstrike查看英文原文
> Use emoji to clarify tone. Compare “:sparkles: :sparkles: Looks good :+1: :sparkles: :sparkles:” to “Looks good.” Or, you know, write "Looks great!" Exclamation mark is the OG emoji
「提问式反馈」并非铁律，团队信任足够时直接给指令反而更高效。
文中建议「提问而非命令」（「你觉得试试……怎么样？」而不是「别这么做」）。我带 6 人团队时做法相反：只要知道有更好的做法，尤其是已有先例或写在规范里的，就一律用祈使句，带主观判断的也照此办理。结果 PR 里讨论得很清楚，零人际冲突，气氛文明而高效。我只是举个例子，不是说哪种对哪种错——这能行得通，是因为我们自始至终是一个团队。
davidrm查看英文原文
> Ask, don’t tell. (“What do you think about trying…?” rather than “Don’t do…”) When I led a team of 6 people, I did the opposite. The guideline was to always use the imperative form if you knew there was a better way, especially if there's a precedent or it's a written rule in a guideline, but even for opinionated things. It resulted in clear debate in PRs, ZERO personal conflicts, everything was very civil and productive. I'm just mentioning this as a personal anecdote, not suggesting that there's a right or wrong way. The reason this worked in my team is because we were, and still are - a team. They're still doing it like that even though I'm no longer involved in day to day.
除了内容本身，何时提醒维护者、如何让人注意到你的 PR 也是写作策略。
希望能更好地支持 PR 的修订。在邮件列表里，每改一版就重发整套补丁；而我把修订后的 commit 强推到分支后，旧 commit 最终会被垃圾回收，尽管 PR 里还引用着它们。另外，PR 礼仪也值得讨论：什么时候适合 @ 维护者？怎么让一个 PR 获得关注？
matheusmoreira查看英文原文
Better support for pull request revision would be nice. In mailing lists, the entire patch set is resent when revisions are made. When I force push revised commits to my branch, the old commits are eventually garbage collected despite the existence of references to those commits in the pull request. Also, it is important to discuss pull request etiquette. When is it appropriate to mention the maintainers? How to draw attention to a pull request?
推荐延伸阅读《Human Code Reviews》，把代码评审当成人际沟通来写。
我很幸运，职业生涯早期就有同事把这篇文章介绍给我：https://mtlynch.io/human-code-reviews-1/ 。直到现在我审代码时还会想起它，整体建议非常扎实。
tommit查看英文原文
I was lucky enough to have a team member introduce me to this article early in my career: https://mtlynch.io/human-code-reviews-1/ I still think about it when reviewing code, it's really sound advice over all
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选