技术文档写作专家

先说清楚它解决什么问题

团队里常见一种死循环：代码写完了，文档还停留在 PR 描述里；接口变了，Swagger 描述却没人同步；新同学入职第一天，先花两个小时从十几个 Markdown 里拼凑 README。文档不是没人写，而是写完没人维护，结构不统一，语气忽而面向开发者、忽而面向业务方。

技术文档写作专家 的价值不在于替你生成一段漂亮的介绍，而是给出一套可复用的写作决策：什么时候该写 ADR，什么时候写入门指南；API 参考应该怎么组织字段；README 到底要包含哪几块才能让贡献者快速上手。

它怎么工作

这个技能的工作方式可以理解为三个层次：

1. 判断文档类型和读者

不同文档对应不同受众和结构：

• API 参考：字段表 + 示例 + 错误码
• 架构文档：ADR + 系统图 + 权衡说明
• 入门指南：前置条件 + 最小可运行路径
• 贡献指南：环境搭建 + 提交规范 + CI 说明\n

技能会先识别你要写的是哪一类，再按对应的结构展开，而不是套同一套模板。

2. 调用具体的写作能力

• 文档最佳实践：统一用词、段落结构、标题层级，让长文档读起来不累
• API 文档设计：生成 OpenAPI/Swagger 规范描述、参数说明和调用示例
• README 与项目文档：从项目目标、安装、使用到贡献路径的完整结构
• 架构文档：ADR 模板、系统图描述和设计文档组织方式
• 用户教程：分步操作指引和引导流程设计
• 文档优化：分析已有文档的模糊点、过时点和断链，给出修订建议
• Doc-as-Code 工作流：把文档纳入 CI/CD、版本管理和自动化发布
• 读者与语气适配：同一套功能，给开发者、终端用户和管理层的表达方式完全不同

3. 给你可直接落地的产出

技能给出的不是抽象建议，而是可以直接放进仓库的文本：带字段表的 API 参考、带检查清单的贡献指南、带 ## 变更历史 的 CHANGELOG 草稿。你可以在它基础上改，省掉从零搭结构的那一步。

适用边界

几个需要说清楚的点：

• 它生成的是文档框架和内容草稿，不是文档托管平台或发布系统
• 优化已有文档时，它依赖你提供的源材料；给的信息越少，改出来的越可能偏离真实意图
• 它不会自动读你的代码库，除非你把相关代码或接口定义贴进来
• 读者适配是个判断题：你需要告诉它这份文档主要给谁看，否则语气可能两头不靠
• 它负责的是写和改，不是翻译。多语言文档请当作独立的写作任务处理