技术写作与文档2020blog.guillaume-gomez.fr编辑精选
如何为 Rust crate 编写文档
How to write documentation for a Rust crate
导读
这是一篇讲如何为 Rust crate 写文档的实操指南，但评论区把它变成了关于"什么才算好文档"的辩论：有人强调示例和自然语言解释不可替代，有人批评自动生成的 API 列表只是索引而非文档，还有人拿 Java、C++ 的文档页做对照，指出分节、摘要、排版对可读性的影响。写作者可以借此重新审视自己的说明性文字：读者是来解决问题的，不是来读源码转述的。
可以直接用的写作要点
- 01
先给可直接运行的示例，再用自然语言解释示例在做什么，让读者不必先建立整体心智模型就能上手。
- 02
不要以为从源码自动生成的 API 列表就是文档，它只是查名字时的兜底索引，真正的文档要交代意图和用法。
- 03
把条目按功能分组（创建、查询、修改、转换等）并加小标题，比一长串平铺的列表更容易扫读。
- 04
在长页面上方给一段摘要或分组概览，方便读者在页内快速定位，而不是从头读到尾。
HN 评论精选
示例加自然语言解释才是文档的核心，自动生成的 API 文档不算文档。
文档最重要的部分是示例：给用户能从中推导出用法的例子，并且要用自然语言解释清楚，而不是把例子丢在 git 仓库某处，让用户先自己构建出库的整体模型才看得懂。图表也会有帮助。很多人以为从源码自动生成 API 文档就算写完了，其实那配不上"文档"二字——自动生成的 API 文档是最后才求助的东西，只适合你已经理解库的理念、只想查个名字的时候用，这点不止对 Rust 成立。
zelphirkalt查看英文原文
Well, I guess the most important part of docs is ... examples! Give your users examples, from which they can derive, how to use parts of your library. Those examples also better be explained in natural language as well and not just somewhere in a git repo, so that the user does not need to build a mental model of the ideas of your library first, before being able to understand your examples. Oh and did I mention diagrams would help? As a professional group, we truly suck at documenting things properly. Many people think, that docs are done once they auto-generated API docs from source code. They are not. That's not something that deserves the name "documentation". Auto-generated API docs are among the last things to turn to, when there is nothing else around or when you already understood the ideas of the library and only need to look up a name of something. That's not only true for Rust, but also for other languages.
好文档要能让读者一键跳到源码，文档与实现的可追溯性本身就是学习资源。
我不理解为什么排第一的评论者体验那么差，我很喜欢 Rust 的文档，在网站上找东西从来不超过几秒，可能只是导航方式需要适应。有地方看不懂时，我可以一键跳进源码弄明白；光读标准库的文档和源码我就学到了很多编程知识，文档是这门语言里我最喜欢的东西之一。
dhruvdh查看英文原文
I don’t know why the experience for the current top commenter has been so poor, but I absolutely love Rust docs, and it never takes me more than a few seconds on the website to find what I am looking for. Perhaps navigating just takes a little getting used to. If something doesn’t make sense to me I can straight away jump into the source code and make sense of it, from a single click. I have learned so much about programming just reading the docs for the standard library, or it’s source code. The documentation is one of my favourite things about it the language.
文档页面要靠分节、分组摘要和对齐排版来支撑扫读，否则只是文字堆。
Rust 文档基本只在你已经知道要找什么时才管用，而且依然难读。对比 String 页面：方法和函数没有任何有用的分节，只是一串列表（在文档注释里加小节就能解决），创建、搜索、修改、测试、转换等方法应该分组；没有利用对齐，只有大块文字；颜色用得差，Java 和 C++ 用颜色和缩进区分签名各部分；也没有摘要，C++ 在点进具体条目之前先概述一组方法，Java 在顶部逐条概述，便于页内检索，而 Rust 还是一整块文字。
jnordwick查看英文原文
Why does the rust documentation still suck? It basically only works if you already know what you ate looking for, and still is difficult to read. Compare the string pages. Rust: https://doc.rust-lang.org/std/string/struct.String.html Java: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html C++: https://en.cppreference.com/w/cpp/string/basic_string Yes, the cop page probably has some bespoke work on the page, but it still demonstrates ideas that are partially auto generated (and most of that page is auto generated). * the method and functions aren't sectioned in any useful way. Just a list of functions (solved by adding section and subsection to the doc comments). Methods that create, search, mutate, test, transform, etc should be sectioned off. * no use of alignment, just blobs of text * poor use of color. Both java and cpp use color to break up sections and alignment to distinguish different parts of the signature. Rust is just a page of text that is very difficult to scan. * no summary. Cpp summarizes the group of method before clicking b through to individual listings, while java summarizes each method at the top. This is useful for searching in a page. Rust is once again just a block of text. * rust also has a unique issue in how to organize traits and other rust specific constructs. It really should have figured this out by now. I can keep going on the uselessness of the rust docs, and I say this as someone who was involved in the language in the past, and give it a new shot about once a year. But the docs have always sucked compared to other languages.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选