技能介绍

开发者文档为什么难写

多数技术团队不缺接口信息，缺的是把接口信息变成可用文档的能力。常见失败模式包括：教程里混入背景解释，读者找不到操作步骤；截图和硬编码版本号随迭代漂移，文档发布即过期；开发者在前 15 秒扫不到返回值或错误码，只能翻源码或提工单；代码示例能编译但没人验证，复制到项目里直接报错。这些问题不是文案问题，而是文档没有按读者任务组织，也没有进入可验证的交付流程。

这个技能如何工作

它以开发者任务为起点，而不是以系统架构为起点。写作前先过五道闸门：

Audience Gate：明确读者是新手、中级还是高级，并据此调整术语密度和代码复杂度。
Diátaxis Gate：判断内容属于 Tutorial、How-To Guide、Explanation 还是 Reference，且不允许在同一篇里混用。
Freshness Gate：识别截图、UI 步骤、固定版本号等高漂移内容，要求加入自动新鲜度检查或缩小范围。
Searchability Gate：检查标题层级、代码块位置和每篇前 100 个词，确保扫读的人能快速定位答案。
Localization Gate：标出习语、文化隐喻、被动句和超长句，降低翻译成本和歧义。

具体产出包括带请求/响应 schema 的 API 参考、可运行的 Python/JavaScript/Go/cURL 示例、Diátaxis 风格的教程和 How-To、MkDocs、Docusaurus、Sphinx 的 docs-as-code 配置、文档审计和改进建议。写作原则是先写代码示例，再用说明文字解释示例；命令、路径、配置和响应一律放进代码块；教程必须列出全部前置条件。发布前按清单验收：每个 API 端点至少一个可运行示例、示例在 CI 中测试、H1 → H2 → H3 不跳级、参数/响应/错误用表格呈现、每段不超过 3 句、删除 Simply、Just、Easily 等填充词。

适用边界

适合撰写或改进开发者用于集成、运维、理解系统的文档，也适合把 OpenAPI spec、代码、changelog 和工程师访谈整理成结构化文档。不适合写营销文案、产品公告或博客软文，这类内容的目标和成功指标完全不同。它记录架构决策，但不替代架构技能做技术选型。它不提供实时系统状态、实时价格等高频变化数据，这类信息应走 API 或动态数据源。它也不替代业务代码实现，只负责文档和参考实现。