技术写作与文档2020github.blog
为什么要写架构决策记录（ADR）
Why Write ADRs
导读
GitHub 博客的这篇文章主张用架构决策记录（ADR）把重要的技术选择写下来。评论区真正在讨论的，其实是一个通用的写作问题：在软件项目里，该把“为什么这样做”写在哪儿、什么时候写、写给谁看。对任何需要向他人解释自己判断的写作者都有参考价值。
可以直接用的写作要点
- 01
记录的重点是“为什么选它、放弃了什么”，而不是复述代码或方案本身怎么运作；读者要的是决策过程，不是说明书。
- 02
凡是偏离默认做法的选择，都必须写在一个容易被找到的地方；写成只有自己知道的笔记，等于没写。
- 03
与其事后由一个人补写文档，不如在设计讨论进行时就异步记录下来，避免文档沦为“我们选了 X，因为 X 看起来最好”这样的官僚文字。
- 04
写文档前先想清楚读者是谁、它多久会过时；否则文档会在没人读的情况下过期，反过来挤占真正做事的时间。
HN 评论精选
非默认决策必须留下可检索的书面理由，口头解释不算数。
不管你用 ADR、代码注释、commit message 还是 README，基本原则只有一条：只要你在软件里做了一个非默认的选择，就要把它写在一个容易找到的地方，让后来看代码的人能明白“为什么”。我经常拦下让人困惑的 PR，问为什么这么写，对方就跑来我办公室解释，或者开始防御；我只好说：“我不是说你代码写错了，我也不想听你口头讲它怎么运作。我要的是把让你做成这样的那些决策写下来。”……不过说实话，多数时候代码确实就是错的。
Pxtl查看英文原文
I think whether you use adrs or comments or git messages or readmes or whatever, the fundamental rule is simple: In any case where you're making a non-default choice in software, it needs to be explained in an easily-discoverable place so a developer that's looking at the project and trying to understand the why of something can see it. Too often I block PRs with confusing code and ask why it was done this way and the developer swings by my office or gets defensive and I have to say "no, I'm not attacking your code as being wrong, and I don't want a verbal explanation as to how it works. I want the decisions that led you to do it this way to be documented". ... But actually usually the code is just wrong.
把决策记录融进异步的设计讨论（issue 评论）里，比事后补一份 ADR 更真实。
有点讽刺的是（毕竟这篇文章是 GitHub 在给 ADR 站台），我恰恰是靠把 GitHub 用得更充分来避开 ADR 的：动手开分支之前，我先开一个内容充实的 issue（写上好几段，链接到相关的 issue 和 PR），并请团队来提意见。设计过程最好以评论的形式异步发生。这样就会留下一份真实、包含多种考量的书面记录。反过来，ADR 常常是事后由一个人补写的，我见过它们退化成官僚文字，比如“我们设计 X 是因为 X 看起来是最好的选项”，这种写法毫无信息量。
vemv查看英文原文
Quite ironically (given it's Github who are defending ADRs in the article), I avoid ADRs by using Github more richly: before working on a branch at all I create a substantial issue (think: multiple paragraphs, links to related issues/PRs, etc) and try to ping the team for feedback. The design process will ideally happen asynchronously, as comments posted in the issue. That way, a truthful trail of diverse considerations will be left in written form. Contrariwise, ADRs can be too written excessively after-the-fact, by a single person. I have seen them degenerate into bureaucracy ("we designed X because X seemed the best option"... how informative).
文档要求若脱离实际资源，只会变成过时又无人读的额外负担。
这类讲工程流程的文章总是把责任全压在具体写代码的工程师身上：不管你的预算和人手有多少，要求都越来越多，非要做到 JPL 级别的成熟度。当然，我们希望每个情况都有单元测试，每条原子 commit 都写详尽的说明，架构文档在过时之前也一直有人读。但与此同时，你还得把本 sprint 的故事点做完，把本季度的 OKR 达成。
rabidrat查看英文原文
These articles about engineering process always put the responsibility solely in the implementing engineer's lap. Always more and more work to achieve JPL-level capability maturity, no matter your budget or headcount. Of course we want unit tests for every case, and verbose explanation in every atomic commit message, and architecture documents that are seldom read before they become stale. But make sure you also get your story points done for this sprint and meet your OKRs for this quarter.
写决策记录的本质，是把难以言传的“程序理论”外化成文字，交给后来的人。
我已经不是第一次在 HN 推荐 Naur 的论文《Programming as Theory Building》了。我觉得这篇文章的想法和 Naur 的论文高度重合：Naur 的论文在讲如何识别那个问题（即程序背后的“理论”难以传递），而这篇讲的是用什么实践去弥合论文指出的知识缺口。
sbuttgereit查看英文原文
This is far from the first time I've evangelized this paper here on HN... but I think the ideas of the OP and the Naur paper "Programming as Theory Building" have a high degree of overlap. Indeed, at some level, the Naur paper deals with identifying the problem while the OP deals with practices to bridge the knowledge gap identified in the paper. http://pages.cs.wisc.edu/~remzi/Naur.pdf
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选