重新思考怎么写文档
自动生成的文档之外，开源项目的文档还应该提供什么。
~/posts/rethink-document-writing $ cat post.md
太多的自动生成文档
用工具生成与 API 一致的文档，是如今大部分项目的选择。对很多开发者来说，依赖生成文档也是又快又时髦的做法——即便有些语言里”生成文档”本身就挺繁琐，调整输出更是麻烦。
生成的文档读起来到底有什么好处？拿 Flutter 举个例子。Flutter 的文档分两类：一类带可交互的页面示例——用户可以直接在网页里改代码、看输出。比如这一篇：https://api.flutter.dev/flutter/widgets/Form-class.html。
这类文档读起来很舒服，直观、易懂。如果你仔细看，会发现这篇文档下方仍然包含自动生成的 API 调用方式。Flutter 大改文档之前，大部分组件确实就只有自动生成的部分。
Flutter 团队推崇并宣传自己 Java-like 的语法风格，这种 JavaDoc 式的文档呈现方式，大约也是从 Java 社区延续下来的。
不需要编译的语言
JavaDoc 被广泛使用。很多 Java 包在 IDE 里写代码时，会主动引导你看 JavaDoc 里的用法说明，而不是直接读源码或反编译结果。一部分 JavaDoc 包含从注释里抽出的函数描述，更多的就只包含输入输出的类型和形参名。
只有类型 + 形参名的 JavaDoc，相对源码阅读的优势恐怕只在”代码被混淆”的场景下成立。即便加上注释抽取的描述，从源码里也能一眼看到一样的内容。
文档不只是类型提示
再看 Dart 和 TypeScript 这类发布时直接附带源码或类型声明文件的语言：要看类型提示，直接读源码就够，JavaDoc 式的文档没什么额外帮助。
那一份好用的文档应该提供什么？我的答案是这几样：
- 心路历程——这个库为什么存在，解决了什么问题。
- 用例——常见用法的几个完整示例。
- 互动展示——能在浏览器里直接跑、改、看效果的部分。
- Q&A——文档作者预料到的常见困惑及其答案。
- 实际情况的解决方案——不是”API 的清单”，而是”想做 X 的时候怎么做”。
总之，从读者的角度出发问一遍：
- 想第一次评估这个方案的用户，需要看到什么？
- 想找到具体用法的用户，需要看到什么？
- 已经长期在用的用户，可能遇到什么麻烦？
类型提示和 API 参考机器可以生成，但上面这几样必须人来写。