工具
如何选择文档生成器，而不是选择一种信仰
Sphinx、MkDocs、Astro 等工具针对不同内容模型和团队优化。应比较作者流程、扩展能力、本地化和维护成本，而不是只看演示页面和功能清单。
2 分钟阅读
内容模型
标签文章: 内容模型
实践
面向持续增长文档的信息架构
五十页时好用的结构，到了五百页可能彻底失效。应围绕用户任务、内容类型和长期稳定的概念设计导航，而不是照搬组织架构。 小型文档集几乎可以容忍任何导航方式。只有二十页时，读者能快速扫完菜单，作者也记得内容放在哪里，重复内容仍然容易发现。
3 分钟阅读
API
OpenAPI 是事实来源，但不是完整的 API 文档
OpenAPI 描述可以生成准确的 reference 结构，但开发者仍需要概念、任务流程、身份认证、示例和错误恢复，这些不是一个 schema 能单独解释的。 OpenAPI 非常擅长描述 operation、parameter、request/response 结构、status code 和可复用 schema。
2 分钟阅读
标准
在数百名贡献者规模下仍然有效的结构化写作规则
规模化一致性来自内容模型、术语和可复用模式，而不是要求所有人背下巨大 style guide。重要规则应写进 schema 和组件。 小团队可以依靠共同习惯和直接编辑。贡献者达到几十或几百人后，记忆就不再是控制系统。
2 分钟阅读