技术写作与文档2022gist.github.com
用 Git 提交信息模板写出更好的提交说明
Using Git commit message templates to write better commit messages
导读
这篇讨论介绍如何用 Git 提交信息模板写出更好的 commit message，核心是让每次提交都说明“为什么做这个改动”。对写作者来说，这是一个很好的类比：用固定模板和提示问题来克服空白页恐惧、养成结构化表达的习惯。
可以直接用的写作要点
- 01
写任何说明文字时，先回答“它为什么存在”——读者（包括未来的自己）最想知道的就是这个。
- 02
用固定模板（如 Problem / Solution / Testing）给表达搭骨架，能降低每次动笔的启动成本。
- 03
模板是学习工具而非永久拐杖：掌握原则后可以简化，但要让反馈（如代码评审）帮你持续改进。
- 04
写完正文后回看原始材料（如 diff），确保描述与实际内容一致。
HN 评论精选
模板是入门工具，配合评审反馈能快速养成好习惯，之后可简化。
这个想法不错，但实践几次提交后你就会掌握所有原则，不再需要模板里的大段提示文字。在 PR 中获得关于提交信息的反馈，能很快强化这些最佳实践（你在做 PR 时会看提交信息吧？）。我是 Conventional Commits 的忠实粉丝，我的模板会提醒我类型并提供实际结构：Problem 描述为什么需要这个改动，Solution 说明改动交付了什么，Testing 说明如何验证，Issue 是关联的工单。
jasonpeacock查看英文原文
This is a good idea, but in practice after a few commits you learn all the principles and don't need a wall of text in your commit template. Getting feedback in your PRs about your commit messages helps quickly reinforce learning these best practices. (you do review the commit message when doing PRs, right? ;) I'm a big fan of Conventional Commits[1], so my commit template reminds me of the types and provides an actual template to describe my change: <type>(optional scope): # type: build ci chore docs feat fix perf refactor revert style test Problem: Solution: Testing: Issue: Where Problem describes why this change is needed, Solution is what this change delivers, and Testing is how this change was validated. Issue is the JIRA/Github issue related to this change. EDIT: The Problem/Solution/Testing/Issue is not part of Conventional Commits, I added those to give structure to the body. [1] https://www.conventionalcommits.org/en/v1.0.0/
写说明时把原始材料（diff）放在眼前对照，能写得更准确。
一个有用的相关技巧：开启 commit.verbose 让 Git 把 diff 附加到提交信息模板里，写提交信息时可以随时对照查看。
greyface-查看英文原文
A useful, related trick. Enable commit.verbose to have Git append a diff to the commit message template, which you can quickly consult when writing a commit message. git config --global commit.verbose true https://tekin.co.uk/2020/03/git-commit-verbose-mode
写作的核心是回答“为什么存在”，为未来的读者（包括自己）服务。
我的提交信息通常只是回答一个问题：“这个提交为什么存在？”因为当未来的我在 git blame 里找到这条提交时，问的正是这个问题。
teeray查看英文原文
My commit messages usually just try to answer the prompt “why does this commit exist?” That’s because future me will be asking that when I open the commit after finding it in `git blame`.
模板若与团队习惯脱节，很容易沦为被忽略的摆设。
出发点很高尚，但据我的经验这些模板往往被无视。我们组织里 90% 的 PR 描述顶部都是没填的空模板文字，加几个空行，然后真正的描述写在下面。
TAKEMYMONEY查看英文原文
A noble effort but in my experience these just get ignored. 90% of the PRs at my org have the empty, unfilled template text at the top of the description, a few line breaks, and then the actual description underneath.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选