技术写作与文档2012github.com编辑精选
如何写出好的 Git 提交信息
Writing good commit messages
导读
这是 Erlang/OTP 仓库的一篇 wiki 短文，讲如何写出好的 commit message：第一行写简短摘要，空一行再写正文，重点解释改动的原因而非细节。对写作者的价值在于：它把"一段文字要给未来的陌生读者看"这件事压缩到极致——如何在几十个字里交代清楚做了什么、为什么做。
可以直接用的写作要点
- 01
第一行用一句话说清这次改动做了什么，控制在 50 个字符左右，空一行后再写详细正文。
- 02
摘要行用祈使句（"Fix crash on empty input"），与 Git 自动生成的合并信息语气一致；若坚持过去时，至少全项目统一。
- 03
正文回答"为什么改"和"改前改后的差别"，不要复述代码已经说清的"怎么改"。
- 04
动笔前先写 commit message，并把摘要行一直放在眼前，能帮自己守住这次改动的边界，不跑题。
HN 评论精选
推荐把 Tim Pope 的文章当作写提交信息的权威参考。
Tim Pope 那篇关于 commit message 的文章才是标杆（tbaggery.com 上的《A Note About Git Commit Messages》）。
briandear查看英文原文
Tim Pope's article on commit messages is the gold standard. http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
对"必须用祈使句"这条规则提出质疑，主张用过去时陈述事实。
祈使句根本说不通。你不是在命令某事应该被做，而是在陈述自己做了什么。除非有非违反常规语法的充分理由，我还是用过去时（或者用 "fixes"、"updates" 这类形式）。
Xcelerate查看英文原文
The imperative form makes no sense. You're not commanding that something should be done -- you're telling what you have done. Unless there's a compelling reason to violate the typical rules of grammar, I will stick with past tense (or alternatively "fixes", "updates", etc.)
先写提交信息再写代码，用摘要行约束自己的改动范围。
有时候先写 commit message、再动手改代码，可能会很有帮助。把摘要行一直显示在编辑器里，也能让自己保持专注。
jpalomaki查看英文原文
Sometimes it feels it might help if one would start by writing the the commit message and then proceeding with the code edits. Might be also good to see the summary line all the time - in the editor just to keep myself focused.
现实中团队往往连一句话都懒得写，能关联工单加一句描述就已算不错。
提交信息？你们的开发者还写提交信息？？？如果我看某个文件的日志，每条提交都带一句话，我就很满足了——当然我说的是公司里的工作，不是开源项目。顺便说一句，企业里更实用的规范是关联工单号，不过有一句描述性的话也确实有帮助（前提是你能让团队真的敲点东西进去，而不是靠强制触发）。
Roboprog查看英文原文
Commit messages? Your developers write commit messages??? If I run a log on a file, and each commit has a sentence, I am a happy man. But of course, I'm talking about work, not an open source project. FYI: a more useful corporate standard is to reference a trouble ticket, although having a descriptive sentence certainly helps (when you can get your team to type anything at all, without a trigger to force it).
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选