用语音输入写出清晰的 Pull Request 描述

修改已经完成，Pull Request 的描述框里却只有“更新文档”。你知道为什么要改，记得哪些细节需要同事再看一眼，也清楚自己检查过什么。但把这些背景写下来，往往又成了一项迟迟没有开始的任务。

可以先用语音输入，像向身旁的同事介绍修改一样讲一遍，再把文字整理成便于浏览的说明。GitHub 的评审指南（英文）也强调说明修改背景。下面这套流程，可以帮助你把自己的讲解变成 PR 草稿。

1. 对照实际改动再开口

在 Mac 上同时打开修改过的文件和草稿文档，或者直接打开 PR 描述框。先读一遍差异，再说明这次提交包含的内容，不要把今天计划做、却尚未完成的工作也算进去。

用一句话交代结果，例如：“这次为贡献者指南添加了环境准备清单。”准确的文件名、议题编号和命令可以留到编辑时复制，不必逐字口述。

2. 按五个问题分段口述

每次说一小段，在项目之间稍作停顿：

• 改了什么？ 说明最终变化，而不是罗列每次编辑操作。
• 为什么要改？ 交代原有问题或缺失的信息。
• 先看哪里？ 指出最需要评审者关注的部分。
• 检查过什么？ 写明已经执行的检查及其实际结果。
• 还剩什么？ 区分待讨论的问题、未验证的情况，以及不属于本次范围的工作。

如果仓库已经提供 PR 模板，就使用现有标题。语音输入只是帮助你起草内容，不需要取代团队约定的格式。

3. 把讲解整理成评审说明

下面是一个虚构的文档修改示例，与 TypeFree 的产品功能无关：

原来的贡献者指南默认读者已经准备好环境，所以我补了准备清单。请先看前置条件部分。我在预览中打开过链接，都能到正确页面，但还没有在全新环境中完整执行配置流程。想请人检查前置条件是否齐全。安装命令没有变化。

编辑后，可以写成：

修改摘要： 为贡献者指南添加环境准备清单，安装命令保持不变。

修改原因： 向首次参与项目的人明确说明需要提前完成哪些准备。

评审重点： 前置条件部分是否遗漏必要步骤。

已完成检查： 在文档预览中逐一打开清单链接，均到达预期页面。

尚未验证： 在全新环境中从头到尾执行配置流程。

这只是写法示例，不是可以直接复用的测试记录。每项检查都应替换为你自己的实际结果。“之后会测试”属于待办事项，不能写成已完成的验证。

4. 编辑时核对精确信息

从原始资料复制文件名和链接，然后确认它们确实属于这次改动。也要检查否定表达：“命令变了”和“命令没有变”描述的是相反的范围，转写时漏掉一个词就可能改变意思。

除非能够解释重要决策，否则删去逐一尝试不同方案的过程。评审者需要理解最终修改的理由，不需要阅读整个下午的工作实录。尚未解决的问题要明确保留，不要为了让文字顺畅而改成确定结论。

5. 最后提出具体的评审请求

把“有什么建议吗？”换成“这份前置条件清单是否包含新贡献者需要的全部准备？”分享之前，再将描述与实际差异、检查结果对照一遍。

类似的写作任务，还可以参考用语音输入写清楚的缺陷报告和更快完成文档草稿。

TypeFree提供了一种把说话转成可编辑文本、加快写作的简单方式。下次写 PR 描述时，先讲清修改的来龙去脉，再补上准确的引用信息，检查无误后再发布。