你花了三天写一份详细的技术文档，覆盖了所有细节，代码示例一应俱全。但发布后，阅读量寥寥，团队也没人提问题。
不是你写得不好，而是你写错了对象。
文档是给谁看的
很多技术文档的问题在于：作者在写给自己看，而不是写给读者看。
你详细解释了架构设计的来龙去脉，但读者只想知道怎么用。你列出了所有可能的边界情况，但读者只关心最常见的那一种。
文档的价值不在于你写了多少，而在于读者能快速找到需要的信息。
三种读者，三种文档
新手用户需要的是入门指南。他们想知道：第一步做什么？第二步做什么？遇到问题去哪里找答案？
进阶用户需要的是最佳实践。他们已经知道基本用法，想知道：这个功能的高级用法是什么？有哪些坑要避开？性能优化的技巧有哪些？
资深用户需要的是参考文档。他们不想要教程，只想知道：这个参数是什么意思？返回值有哪些可能？API 的边界条件是什么？
把入门指南写给资深用户看，或者把参考文档写给新手看，都是浪费时间。
写文档前先回答三个问题
- 谁会读这个文档？
- 他们想解决什么问题？
- 他们已经有了什么知识？
如果答不上来，别开始写。先搞清楚读者，再动笔。
从用户场景出发
不要按"这个功能有什么"来组织文档，要按"用户想做什么"来组织。
好的结构是："如何创建一个项目"、"如何部署到生产环境"、"如何排查常见问题"。
不好的结构是："命令行参数说明"、"配置文件格式"、"API 接口列表"。
前者是以用户为中心，后者是以系统为中心。用户只关心自己能做什么，不关心你的系统怎么设计的。
示例比解释重要
一个具体的例子，胜过一千字的抽象说明。
不要说："这个函数接受一个对象作为参数"。要说：你可以这样调用：createUser({name: "Alice", age: 30})。
读者看到示例，立刻就能理解。看到抽象说明，还要再想一遍。
文档是用户体验的一部分
很多人把文档当成代码的附属品，写完代码再随便补点说明。
但文档是用户接触你的系统的第一站。文档写得好，用户愿意尝试。文档写得烂，用户直接放弃。
好的文档是产品的一部分，甚至比代码本身更重要。代码好但文档烂，用户用不起来。代码一般但文档好，用户至少能用起来。
如何改进
下次写文档前，先找一位目标读者，问他："你想在这个文档里找到什么？"
然后按他的需求来写，不是按你的想法来写。
文档不是证明你理解了系统，而是帮助读者理解系统。这个区别很小，但影响很大。
—— https://www.80aj.com