技术写作与文档2011github.com
Linus：请写好 Git 提交信息
Linus: please write good git commit messages
导读
这是 Linus Torvalds 在 Subsurface 项目 README 中写的一段关于如何写好 git commit message 的规范，被 Hacker News 拿出来讨论。它值得写作者读，因为提交信息是大多数人每天都要写的最实用的说明文：如何在极短篇幅里说清“改了什么、为什么改”，以及如何为读者（未来的自己和同事）着想。
可以直接用的写作要点
- 01
第一行用一句话概括这次改动做了什么、为什么做，细节和背景放到正文里展开，别让读者靠 diff 去猜。
- 02
避免“Edited path/to/file”这类默认占位信息——它没有提供任何 diff 之外的新信息，等于没写；宁可留空，逼自己动手写一句有内容的话。
- 03
手动换行、把每行控制在约 74 个字符以内，既方便阅读，也方便在终端和引用回复中被完整呈现。
- 04
把 git log 当成一部关于项目的连载博客来写，让后来的人能顺着提交历史读懂项目的演进思路。
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选