技术写作与文档2021news.ycombinator.com编辑精选
Ask HN：你如何撰写文档？
Ask HN: How Do You Write Documentation
导读
这是一位刚入职的工程师在 Ask HN 上的求助：团队代码库几乎没有文档，新人上手极其痛苦，他想主导一次文档重整，却说不清“好文档”和“坏文档”的分界线在哪里。讨论中几位老手给出了可操作的文档分类框架——架构说明、教程、参考、解释各司其职，以及“在哪找、怎么做、为什么这样做”这三个必须回答的问题。对任何写说明性文字的人都有参考价值：它讲的是如何按读者的需求拆分信息，而不是把所有内容堆成一大坨。
可以直接用的写作要点
- 01
把文档按读者任务拆成几类：架构概览（模块职责、范围与非目标）、教程（常见任务怎么做）、参考（接口细节）、解释（为什么这样设计），不要混成一份大杂烩。
- 02
架构文档要短，但一定要写清“非目标”——明确说明什么不在范围内，比罗列功能更能帮新人建立边界感。
- 03
每份文档都应回答三个问题：这个功能在哪里、它是怎么实现的、为什么要这样实现；前两个靠简图和教程，最后一个靠架构决策记录。
- 04
能通过代码本身（命名、类型、docstring、IDE 内联提示）表达的信息就不要写进文档，让文档只保留代码说不清的部分。
HN 评论精选
文档按“架构—教程—参考”三层组织，并尽量让代码本身承担参考部分。
我会写那种能帮我自己快速熟悉一个代码库的文档。第一是架构：有哪些模块、各自负责什么、什么在范围内、什么不在范围内（非目标特别重要），这部分要短。第二是教程：演示用这份代码做常见任务的步骤，这是传达预期生命周期和最佳实践的好方式。第三是参考：细节，我认为接口调用约定最重要；但更希望尽量消灭这类文档，让错误用法根本无法表达。如果团队用 IDE，就把这部分写成能在自动补全和内联提示里出现的形式。
vnorilo查看英文原文
I write the kind of documentation that would help me to get to know a codebase quickly. - Architecture: what modules are there, what are their responsibilities? What is in scope and out of scope (non-goals are super important). Keep this short and sweet. - Tutorials: Show how to do some common tasks with the code. A good way to communicate intended life cycles and best practices. - Reference: Details. I feel API contracts are the most important. I prefer trying to eliminate this type as much as possible, by trying to make invalid usage unrepresentable. If your team uses IDEs, consider putting this in a format that shows up in autocomplete/inline docs. How much you need this depends a lot on if you're working with dynamic or static types.
推荐 Divio 的四类文档框架：教程、操作指南、参考、解释。
这可能正是你要的：Divio 提出的文档四种类型（https://documentation.divio.com/），简言之就是教程、操作指南、技术参考和解释说明。HN 上讨论过两次，链接在帖中。
oefrha查看英文原文
This may or may not be what you need: Four kinds of documentation https://documentation.divio.com/ (In short: tutorials, how-to guides, technical reference and explanation.) Discussed at https://news.ycombinator.com/item?id=21289832. Edit: Apparently discussed again at https://news.ycombinator.com/item?id=26002656.
用 C4 模型回答“在哪”、教程回答“怎么做”、ADR 回答“为什么”。
我认为好的文档必须回答三个问题：我在哪里能找到这个功能？它是怎么实现的？为什么要这样做？描述性的结构图可以解决“在哪里”，比如 C4 模型，它比 UML 简单，一次只聚焦项目的一个部分。教程适合展示一个用例以及如何用项目解决它，回答“怎么做”。最难的是 ADR（架构决策记录），把项目中的每个决策都记录下来，回答“为什么”。补充一点：我们的 ADR 就是 PR，因为禁止直接向主分支提交，所有代码都要经过评审。API 文档则写在代码内的注释和 docstring 里，IDE 能直接读取并在写代码时提示。
linkdd查看英文原文
In a good documentation, IMHO, you must answer the following questions: - where can I find this functionality? - how is it done? - why is it done this way? You can do a lot with descriptive schemas, take a look at C4 models[1], they are simpler than UML and focus on a single part of your project at a time. This should answer the "where". Tutorials are a good way to present a use case and how to solve it using your project. This should answer the "how". Then, the most difficult part for me are ADR[2] (Architectural Decision Record), to document all decisions within the project. This should answer the "why". EDIT NB: Our ADR is our PRs since committing directly to master/main is forbidden and all code should be reviewed API Documentation is then done with comments/docstrings within the code itself, and usually the IDE knows how to read it and help you directly while you write code. [1] - https://c4model.com/ [2] - https://adr.github.io/
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选