技术写作与文档2022cbea.ms编辑精选
如何写好 Git 提交信息（2014）
How to write a Git commit message (2014)
导读
这篇经典文章讨论如何写出好的 Git 提交信息，评论则把话题延伸到简洁表达、结构化和长期可追溯。对写作者来说，它是一堂微型写作课：如何在极短篇幅里交代做了什么、为什么做，并让未来的读者看得懂。
可以直接用的写作要点
- 01
用“标题+要点”组织信息：先给一句结论，再用短条目列出关键改动，比连续叙述更快被读懂。
- 02
别只写“做了什么”，要补上“为什么这么做”，否则信息很快失效，后人难以判断。
- 03
把文字当成会随作品长期保存的档案来写，提供自足上下文，不要依赖临时讨论区里的补充说明。
- 04
可用“feat/fix/chore”这类类别前缀训练分类表达，让读者一眼判断内容类型，也方便后续检索。
HN 评论精选
提交信息随仓库长期保存，PR 讨论不会，因此要在 commit 里写自足、可长期追溯的上下文。
我猜这里不少评论者写代码才不到15年。有意思的是，git 差不多15年来都是事实上的版本控制系统，这意味着你写进 commit message 的内容很可能会一直留存。作为一个老手，我用过基于文件的备份、SCCS、CVS、SVN，现在用 git。迁移来迁移去，90年代的量化代码到2022年还在跑，而我们有 commit message 为证。上面有人提到 PR 是深度信息的来源。但 PR 只是另一个 issue tracker；commit 会随仓库走，PR 讨论不会。
DrBazza查看英文原文
I'm sure quite a few commenters on here only started writing code in the last 15 years. What's interesting is that git is (more or less) the de facto version control system and has been for that 15 years, and that likely means that what you put in your commit messages will stay around forever (for some definition of forever). As a greybeard I've gone file-based backups, then SCCS, CVS, SVN, and now git for what seems like forever (git was 2005 according to wikipedia), though probably the late 00s. And migrating from one to the next (yes, quant code from the 90s is still running in 2022, and we have the commit messages to prove it). Some people commenting above/below above the PR being the source of in depth information. As far as PRs are concerned, it's just another issue tracker, and I've been through the lot, also including various git hosting services). The commits travel with the repository. The PR discussions don't.
用约定式前缀标明变更类型，让信息可扫描，也能驱动自动化。
我喜欢 conventional commit 风格。你可能在开源仓库或工作中见过：feat: support new line chart / fix: update props for new line chart / chore: bump dependency version。更酷的是有工具（semantic release）会根据提交类型（feat、fix、chore 等）自动决定下一个版本号并发布模块。
bern4444查看英文原文
I like the conventional commit style [0]. You may have seen these in open source repos or used them at work. They look like feat: support new line chart fix: update props for new line chart chore: bump dependency version What's also cool is there are tools (semantic release) that will then handle automatically the versioning and publishing of your module based on these commits using the commit type (feat, fix, chore etc) to determine the next appropriate version [1]. [0]https://www.conventionalcommits.org/en/v1.0.0/ [1]https://github.com/semantic-release/semantic-release
标题加要点比叙述更高效，能迫使作者先给结论、再列关键改动。
标题+项目符号更快传达有用信息，简洁易读。例如：improve Buffer Cache Management & logging；- change 'tryDrop()' to skip immediately, if lock unavailable；- move BufferCache logging to a separate logger；- attach BufferTrim.Unsuccessful -> Preemptive Flush of oldest buffers。我在很多代码库和内部文档里工作过，发现叙述体读和写都明显更低效。在 commit message 里，太多开发者几乎不写改了什么、为什么改；叙述格式的缓慢可能助长了这一点。在 Wiki 等文档里，叙述会鼓励开发者絮叨次要技术细节，却漏掉高层上下文。标题+要点绕开了叙述的很多困难：先给标题，然后切到重点。
twhitmore查看英文原文
Interesting topic. From my experience Headline + Bullet Points are far quicker to convey useful information, in a form that is terse yet easy to read. For example: ---------------- improve Buffer Cache Management & logging - change 'tryDrop()' to skip immediately, if lock unavailable - move BufferCache logging to a separate logger - attach BufferTrim.Unsuccessful -> Preemptive Flush of oldest buffers -------------------------------- Having worked in many codebases & internal docs, I've found narrative significantly less efficient to read & write. In commit messages, far too many developers skip almost any detail as to what they're changing & why -- the slowness of narrative formats may substantially contribute to this. In docs (Wiki etc), narrative encourages developers to ramble about minor technical details while omitting all high-level context. Headline + bullet-points bypass a lot of struggles with narrative by allowing a simple headline and then, well, cutting to the point. This also illustrates a informed personal preference -- studies find lowercase English words faster to scan/ comprehend. See: http://literatejava.com/git/how-to-write-a-good-git-commit-message/
写作规则常被误传为硬性限制，应以清晰传达为准，而不是迷信长度。
我讨厌50字符那条规则。据我所知，它起源于有人注意到 Linux 内核的平均提交信息约50字符，然后不知怎么变成广泛传播的教条，说最大长度应该是50字符。
ufo查看英文原文
I hate that rule about 50 characters. IIRC, it started because someone noticed that the average commit message in the linux kernel is about 50 characters. Then, for whatever reason it morphed into this widely propagated mantra saying that the maximum should be 50 characters.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选