Technical Writer

技术文档撰写

将复杂的技术概念转化为清晰、易懂的文档，帮助用户顺利完成任务。这项技能专注于编写 API 文档、用户指南、README 文件、教程和参考资料，兼顾技术准确性与易读性。

无论是为代码库、软件产品、系统架构还是流程编写文档，这项技能都能确保文档内容全面、组织有序且切实有用，并遵循行业最佳实践，规范文档结构、格式和内容组织方式。

适用于需要创建技术和非技术受众都能理解并有效使用的文档的软件开发者、DevOps 工程师、产品经理和技术团队。

核心工作流

工作流 1：API 文档

1. 分析代码库 - 检查 API 端点、参数和响应
2. 组织参考内容 - 按资源/端点分类，并保持格式一致
3. 编写端点文档 - 撰写清晰的说明、参数介绍以及请求/响应示例
4. 添加代码示例 - 提供多种语言的示例
5. 创建快速入门 - 编写包含身份验证的入门指南
6. 构建错误参考 - 记录错误代码并提供故障排除说明
7. 生成 OpenAPI 规范 - 创建机器可读的 API 规范

工作流 2：创建用户指南

1. 分析受众 - 确定用户角色和技能水平
2. 梳理任务 - 列出所有用户任务和工作流
3. 规划内容大纲 - 根据用户旅程而非功能组织指南
4. 编写操作步骤 - 创建配有屏幕截图的分步说明
5. 补充背景信息 - 不只说明如何操作，也解释原因和适用场景
6. 构建导航 - 创建清晰的目录、索引和搜索关键词
7. 测试文档 - 根据真实用户场景验证文档

工作流 3：编写优秀的 README

1. 项目概述 - 用一段话说明项目的功能
2. 安装 - 提供清晰的设置说明和前置条件
3. 快速入门 - 提供最简示例，帮助用户快速运行
4. 使用示例 - 提供贴近实际的代码示例并加以说明
5. 配置 - 记录所有选项、环境变量和标志
6. 贡献指南 - 说明贡献方式和开发环境设置
7. 许可证与致谢 - 提供法律信息和致谢内容

工作流 4：架构文档

1. 系统概述 - 提供高层次图示和说明
2. 组件拆解 - 详细介绍各个主要组件及其职责
3. 数据流 - 记录信息在系统中的流转方式
4. 部署 - 说明基础设施、扩展和监控方面的注意事项
5. 安全模型 - 说明身份验证、授权和数据保护
6. 决策记录 - 记录架构决策及其依据

快速参考

操作	命令/触发语
创建 API 文档	"Document this API"
编写 README	"Create README for this project"
用户指南	"Write user guide for [feature]"
故障排除章节	"Create troubleshooting guide"
教程	"Write tutorial for [task]"
发行说明	"Generate release notes from changes"
迁移指南	"Write migration guide to [version]"
代码注释	"Document this code"

最佳实践

• 先说明原因 - 深入细节前，先解释目的和使用场景
• 展示可运行的示例 - 每个概念都需要具体的代码示例
• 保持一致 - 全文使用相同的术语、格式和结构
• 便于快速浏览 - 灵活使用标题、列表、表格和代码块
• 全面测试 - 验证所有代码示例都能正常运行
• 明确版本 - 标注每项功能或行为适用的版本
• 主动更新 - 让文档与代码变更保持同步
• 合理添加链接 - 关联相关概念，同时避免信息过载
• 使用图表 - 复杂流程需要直观呈现
• 便于搜索 - 针对 Ctrl+F 和站内搜索进行优化
• 提供背景信息 - 不仅说明如何使用，还要说明何时以及为何使用
• 妥善处理错误 - 记录常见错误及其解决方案
• 兼顾国际化 - 使用清晰、简单且易于翻译的语言
• 注明前置条件 - 绝不假定读者具备相关知识
• 提供快速成果 - 帮助用户在 5 分钟内取得成果