技术写作与文档2014news.ycombinator.com编辑精选
Ask HN：如何写好文档？
Ask HN: How do I write good documentation?
导读
这篇 Ask HN 讨论如何为 PHP 框架写出真正有用的文档，而不是堆砌无益说明。核心共识是：先明确读者和目的，把文档当作“销售页 + 技术说明”的组合，并用示例、设计意图和知识差来降低理解成本。对写作者来说，它提供了可迁移的说明文写作方法。
可以直接用的写作要点
- 01
先定义目标读者和要帮他们完成的任务，区分“评估是否采用”和“开始使用”两种阅读心态。
- 02
每个 API 或方法不要只说明功能，还要给用法示例、设计意图、权衡取舍和常见最佳实践。
- 03
列出“你已知”与“新读者未知”的知识差，从最大、最简单的问题开始，用最简洁的方式补齐。
- 04
多读优秀框架文档，观察它们在结构、清晰度、完整性和简洁性上的取舍，再反推自己的写法。
HN 评论精选
文档首页要承担“说服采用”的销售功能，深入部分再提供扎实技术细节。
你不只是在写文档，也是在为框架写销售文案。开发者读 API 文档时有两种心态：1）评估阶段：他想判断框架能否在自己的约束下解决问题，会快速浏览关键词和类似示例；2）实施阶段：他已初步选定框架，准备做第一个项目，文档的技术质量会影响他完成还是放弃。文档首页应把开发者从评估阶段转化到实施阶段，所以介绍页要像销售页：为什么用、有哪些生产案例、有什么好例子；更深处的文档则要扎实的技术说明。
chatmasta查看英文原文
You are not only writing documentation. You are also writing sales copy for your framework. Recognize that developers will come to your API docs with two possible mindsets: 1) Evaluation stage: Developer arrives at API docs with goal of determining whether framework solves problem within unique set of constraints. Expect him to skim docs, searching for keywords related to constraints, and/or any examples similar to problem. 2) Implementation stage: Developer has settled on your framework (at least initially), and is ready to build first project. Will either complete project, or abandon framework, depending on technical quality of your docs. These two mindsets represent two components of a sales funnel. On the docs landing page, your primary goal should be converting developers from Mindset #1 --> Mindset #2. If you look at popular docsets, you'll notice that the intro pages tend to read like sales pages. Why should you use this framework? What are some popular production implementations? Any cool examples? Deeper in the docs, you simply need solid technical documentation. Other comments here have great tips. Just keep in mind that Mindset #1 will barely skim these areas of your docs, but will definitely consider them briefly. So, in brief: 1) Sell developers. 2) Write good technical docs.
API 文档要用示例讲清用法、设计意图、权衡和与代码库的关系。
在 API 层面，不要只解释东西做什么，还要说明怎么用、某个调用或方法背后的意图，以及它如何与环境中其他部分集成。有最佳实践就在这里点出来；不一定要写成教程，但很适合放“用法示例”。可以重点回答：实现时做了哪些决定？有哪些权衡（为什么这样写）？应该怎么用？访问资源的常见模式是什么（实例化、工厂、单例、依赖注入）？它和代码库其余部分如何关联？在其他语言里还可说明是否线程安全、创建新对象成本高不高。
ricardo_ramirez查看英文原文
This is personal, but I taught myself how to code, before the internet, and with barely any books. One thing that made, for example, the PHP documentation a lot easier to read vs. Perl was: examples On an API level, don't just explain what things do, but how to use it, what is the intention behind a particular call or method, and how it integrates with other pieces of the environment. If there are best practices, this is the place to call them out. And it does not need to be a tutorial, but if the class calls for a "usage sample", that is perfect for the documentation. Pick on these: 1) What decisions did you take for the implementation? 2) What tradeovers are made (this is written like this because ...) 3) How is it supposed to be used 4) What is the common pattern for accessing the resource (instantiate it, factory, singleton, dependency injection?) 5) How does it relate with the rest of the codebase? Now, this is PHP, but on other languages... 6) Is it Thread-Safe? 7) How cheap is it to instantiate a new object of that type?
写作就是识别作者与读者之间的知识差，并按从大到小、简洁地补齐。
先确定文档的目标读者是谁、你要帮他们做什么。然后把头脑分成两半：一半装你对项目的全部了解，另一半装假想的新读者所知（可能一无所知）。找出这两套知识之间的每个差异，从最大、最简单的开始，用尽可能简洁的方式写出读者需要知道什么，才能从一个状态过渡到另一个状态。如果开始漫无边际，就回头删改。这个方法不只适用于软件项目。
rogual查看英文原文
First you should decide who the intended audience of your documentation is. Who are you trying to help, and what are you trying to help them do? Then, partition your mind into two halves. The first half contains everything you know about the project, and the second half contains everything your imaginary new reader knows, which may be nothing. Identify each difference between these two bodies of knowledge and, starting with the largest and simplest, write down what the reader needs to know in order to transition from one state of mind to the other, in as succinctly a way as possible. If you start rambling, go back and edit. I find this works for explaining many things, not just software projects.
多读优秀框架文档，分析其结构与表达取舍，是提升文档写作的有效途径。
想提高写文档能力，就去读别人的文档。观察作者（隐含地）做了哪些选择，以及在结构、清晰度、完整性和简洁性上什么对你有效。可以看受众广的 Web 框架文档，例如 Django、Symfony、Rails 的指南和 API 文档。
jschulenklopper查看英文原文
> How do I get better at writing documentation? Read other documentation. Discover what choices the writers made (implictly) and what works for you w.r.t. structure, clarity, completeness, conciseness. In your case, look for documentation of other (web) frameworks with a large audience, for example: - Django: https://docs.djangoproject.com/en/1.7/ - Symfony: http://symfony.com/doc/current/book/index.html - Rails: http://guides.rubyonrails.org/ and http://api.rubyonrails.org/
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选