技术文档该写到「什么程度算够」：细节堆满还是留白给读者？

背景 做了 8 年技术文档，最近复盘自己经手过的项目文档，发现一个反复出现的尴尬：同一份「接口接入指南」，有人看完直接上手跑通了，有人看完还是来问「这一步到底点哪里」。差别往往不在读者能力，而在文档的颗粒度——它决定了读者能自己走多远。

我见过的三种流派

1. 极简派：只写「是什么 + 关键命令」，假设读者能自己拼。优点是可维护、不易过时；缺点是新人卡在第一个坑就劝退。
2. 全量派：每个参数、每个分支、每段报错都写全，甚至贴完整配置。优点是「照抄就能跑」；缺点是文档膨胀、一改就大面积失修，三个月后没人敢信。
3. 分层派：正文只给主路径 + 最小可跑示例，细节、边界、排错拆到附录或 FAQ，按需展开。

我的倾向 我偏向「分层 + 可复现」，理由有三：

• 读者目的不同：有人要 5 分钟跑通 demo，有人要排查线上问题，一份文档不可能都满足，硬塞只会两边都不满意；
• 可维护性：主路径稳定、细节易变，分层后「易变」部分失修不影响主干可信度；
• 可复现优先：与其写满「理论上应该怎样」，不如给一条「我实际跑通过」的最小命令/配置，哪怕只覆盖 80% 场景。 但我也纠结：分层的前提是判断读者是谁，而很多团队根本没有清晰的读者画像，最后只能全量堆。

想听大家聊聊

• 你们团队写文档时，有没有「读者画像」？还是默认「写给下一个自己」？
• 细节堆满 vs 留白，你在什么场景下会怎么选？（比如：对外 API 文档 vs 内部 runbook vs onboarding 手册）
• 你们怎么衡量一份文档「够不够」——是按新人上手时间，还是按工单量/重复提问次数？

欢迎贴你们的具体做法或反例，我想收集一些可对照的样本。