技术写作与文档2015chris.beams.io编辑精选
如何写好一条 Git 提交信息
How to Write a Git Commit Message
导读
这是程序员圈里流传甚广的一篇写作指南：如何把 Git 提交说明写清楚。它给出的规则（短标题、空行分隔、祈使语气、正文讲清「为什么」）其实是通用写作训练的缩影——限制字数、先写结论、为读者交代动机，因此很值得写作者读一读。评论区最有意思的分歧在于：有人指出提交说明常常「说谎」，根本问题出在一次提交里塞了太多改动；也有人质疑「祈使语气」这条铁律是否真的成立。
可以直接用的写作要点
- 01
标题控制在一行、约 50 字以内，把「做了什么」压缩成一句可独立成立的短句。
- 02
标题与正文之间空一行，正文回答「为什么改、改了什么」，而不是复述代码怎么改。
- 03
每一条只讲一件事：把多个改动拆开写，比在一条里笼统概括更可信。
- 04
动笔前想清楚读者是谁、他要拿这条信息做什么，再决定语气和信息密度。
HN 评论精选
一次提交只做一件事，比事后写漂亮的说明更重要；不完整的说明比没有说明更误导人。
提交说明最大的问题是它们会说谎。原因是大多数人一次提交里塞进了多个互相独立的改动，而说明里往往只提「主要改动」。结果排查问题时，人们读到那条不完整的说明，会想「问题不可能出在这里，这次只改了 X」，可实际上还改了 Y 和 Z。所以我个人觉得，与其写说明，不如保证每次改动足够小，让人直接看代码就能明白发生了什么。比如 Django 项目里有些提交，看文件差异比看提交说明更容易搞清发生了什么。（他还提到，如果有工具能做语义级的差异总结而不是逐行 diff，会大有帮助。）
ThePhysicist查看英文原文
The biggest problem with commit messages: They lie. The main reason for this is that most people tend put more than one atomic change into a single commit, but in the message they often only mention the "main change" which they introduced with the commit. This in turn makes it much harder to find out which commit introduced a given problem into the code base since people will usually read the (incomplete) message of a given commit and think "the problem can't be here because this commit only did X" while it actually did Y & Z as well. So, personally, I think we could as well abandon writing commit messages entirely and instead make sure that individual changes are small enough so that we can figure out what happened by looking at the actual code instead. As an example, if you look at individual commits in the Django project (such as this one: https://github.com/django/django/commit/e7e8d30cae9457339eb49ae8584e82ff0a038e99), it is often much easier to figure out what happened by looking at the file diff than the commit message. A tool that could summarize changes in source code using advanced (semantic) diffing instead of line-by-line diffs would make this much easier of course.
语气规则要服务于区分「谁做了什么」，统一用祈使语气反而增加读者的理解成本。
在关于 Git 提交说明的各种常见建议里，「标题一律用祈使语气」是我最难认同的一条。用祈使语气描述提交者自己的动作，听起来确实别扭，但更糟的问题是：它模糊了「系统的行为」和「提交者的行为」之间的区别。在我自己的项目里，描述系统应该做什么时用祈使语气（如「不要在缺少缓存目录时警告用户」），描述我自己的动作时用陈述语气（如「移除了不必要的缓存目录警告」）。我注意到有些项目两种情况都用祈使语气，我怀疑这会给浏览提交日志带来额外的认知负担。一个解决办法是标题里永远不「对系统说话」，但那样往往就不再是最简短、最有表现力的说法了。
networked查看英文原文
Out of all common advice on Git commit messages always using the imperative mood in the title I find the hardest to agree with. Describing your own actions as a committer in the imperative may sound strange, true, but there is the worse problem of making less obvious the distinction between the actions of the system and those of the committer. In my own projects I use the imperative when describing the actions the system should perform ("Don't warn user about missing cache directory") but use the indicative mood when describing my own actions ("Removed unnecessary cache directory warning"). I've noticed that some projects use the imperative for both cases and I suspect this introduces a degree of cognitive overhead to scanning the commit log. One solution to this problem would be to never "address the system" in the commit title but I find that that is often the shortest and the most expressive way to describe an update.
说明文字可以读成「历史记录」而非「指令」，时态和语气的选择取决于读者怎么用它。
大多数人真的会把提交说明读成「如果应用这个提交，它将会……」吗？我一直把日志当作事件的历史来读，也就是描述过去发生了什么——这次提交「修复」了什么，那次「改动」了什么，「重构」了、「实现」了等等。
divan查看英文原文
Does the majority read commit messages as "If applied, this commit will..."? I always treated log messages as a history of events, i.e. describing what had happened in the past - this commit "fixed" something, and this one "changed" something, "refactored", "implemented", etc.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选