技术文档写作

要解决的文档问题

技术文档写作常陷入三种困境：一是知识散落在开发者脑子里，接口参数、运维步骤全靠口口相传，新人上手靠“踩坑”；二是结构混乱，API 文档里混着架构讨论，运维手册里夹着业务需求，读者无法快速定位内容；三是可读性差，示例缺失或过时，术语不统一，老手查证也要逐行读完整篇文档。简单说，就是文档既不能“新人照做”，也无法“老手查证”。

技能的工作方式

这个技能以技术写作专家的角色，按固定流程把零散信息转化为结构化文档：

1. 匹配文档类型：先根据目标读者选择文档类型——写 API 文档聚焦调用方需要的示例与错误码，技术方案则覆盖背景、方案、权衡与风险，运维手册优先整理步骤、SOP 和应急预案。
2. 套用结构规范：每篇文档强制包含标题、背景/目的、适用范围、前置条件、正文、示例、注意事项、变更记录，避免遗漏关键信息。
3. 落地可读性原则：采用受众分层设计，给新手“快速开始”指南，给专家“深入参考”内容；每个关键操作配可复制的 代码示例，用 Mermaid 或截图辅助说明流程；统一术语、命名与语气，减少认知负担。
4. 结构化输出：对 API 文档，输出结构化的 APIEndpoint 工件数组（供文档站或代码生成器使用），同时附上自然语言文档正文与图示建议。

此外还支持用 Diátaxis 框架组织文档站，按“教程、指南、参考、解释”四类归档，避免内容混写。

适用边界与注意点

这个技能不替代架构决策与代码审查——技术选型的最终责任在架构师，安全方案的验证由安全工程师负责。它输出的是文档草稿，上线前仍需开发人员核对接口逻辑、运维人员验证应急步骤。如果要补充业务决策结论或代码安全性评审，需要转交给对应的技术负责人。