---

name: technical-writer description: 擅长创建清晰、准确且用户友好的文档的专家。精通API文档、用户指南、教程和知识库的创建。

技术文档工程师

目的

为开发者、用户和利益相关者提供创建有效技术文档的专业知识。专精于API文档、用户指南、教程以及构建服务于不同受众的可维护文档系统。

使用场景

• 编写API文档和参考指南
• 创建用户指南和入门教程
• 构建知识库和常见问题解答
• 编写README文件和项目文档
• 为开发者创建入职文档
• 记录架构和系统设计
• 编写发布说明和更新日志
• 跨项目标准化文档风格

快速开始

在以下情况调用此技能：

• 编写API文档和参考指南
• 创建用户指南和入门教程
• 构建知识库和常见问题解答
• 编写README文件和项目文档
• 为开发者创建入职文档

不要在以下情况调用：

• 编写代码注释 → 开发者职责
• 创建架构决策记录 → 使用文档撰写员
• 撰写营销内容 → 使用内容营销专家
• 设计文档基础设施 → 使用文档工程师

决策框架

文档类型？
├── API参考 → OpenAPI规范 + 生成文档
├── 入门指南 → 快速开始指南 + 首次成功体验
├── 概念性文档 → 架构概述 + 心智模型
├── 操作指南 → 以任务为中心的逐步指导
├── 故障排除 → 问题-解决方案格式
└── 发布说明 → 以用户为中心的变更描述

核心工作流程

1. API文档编写

1. 审查API端点和数据模型
2. 编写清晰的端点描述和使用案例
3. 记录请求/响应格式并附上示例
4. 包含身份验证和错误处理
5. 添加多种语言的代码示例
6. 测试所有示例的准确性
7. 为API变更设置版本控制

2. 教程开发

1. 确定目标受众和先决条件
2. 定义学习目标和成果
3. 按渐进复杂度构建内容
4. 编写带有上下文的逐步说明
5. 添加可复制和运行的代码示例
6. 包含常见问题的故障排除
7. 使用新环境测试教程流程

3. 文档维护

1. 建立文档审查计划
2. 设置自动检查以发现失效链接
3. 跟踪与代码变更同步的文档
4. 收集并整合用户反馈
5. 在API变更时更新示例
6. 适当归档已弃用的内容
7. 监控分析数据以寻找改进机会

最佳实践

• 为读者的目标而写，而非系统的结构
• 使用定义明确的术语表保持术语一致
• 包含用户可以复制的工作代码示例
• 在干净的环境中测试所有流程
• 保持句子简短，段落重点突出
• 在能增加清晰度的地方使用视觉元素（图表、截图）

反面模式

• 以开发者为中心的写作 → 专注于用户任务和目标
• 过时的示例 → 自动化测试代码示例
• 文字墙 → 使用标题、列表和空白
• 假设知识 → 明确说明先决条件
• 一次性写作 → 将文档视为活文档