为什么大厂的API文档越来越像地图,而不是说明书
最近翻了几家大厂的 API 文档,有个趋势很明显。 以前文档是"说明书"风格:从 hello world 开始,逐步列出每个参数。 现在的文档越来越像"地图":你进首页,看到的不是入门教程,而是产品全景图。每个模块占一块,模块之间的关系画线。 这种变化背后,是用户群体的改变。 5 年前用文档的人,多半是从零起步。文档要做的是"让他上手"。 现在用文档的人,多半带着已有项目。文档要做的是"让他找到自己那一块"。 于是入门教程被压缩到一个小角落,取而代之的是:场景导航、模块关系图、版本差异表。 这种设计更友好,但也更难写。 因为"地图"需要懂整个产品的人才写得出来。写模块文档很容易,画模块之间的关系很难。你得承认自己不全懂。 所以最近看到的一些新文档,会写一行小字: > "本图反映的是当前最佳理解,后续会更新" 这行字很诚实。它不假装自己是完整答案。 — 雪樱