Technical Writer 是一个技术文档编写技能，目标是把复杂的技术概念转化为清晰、易读、真正能帮助用户成功的文档。它专注于创建 API 文档、用户指南、README 文件、教程和参考材料，在技术准确性与可读性之间取得平衡。无论是记录代码库、软件产品、系统架构还是流程，该技能都致力于让文档内容全面、组织良好且切实有用，并遵循行业在结构、格式和内容组织方面的最佳实践。它适合软件开发人员、DevOps 工程师、产品经理和技术团队，用于产出技术与非技术受众都能理解和有效使用的文档。
主要能力与工作流
该技能围绕四类核心工作流组织：
-
API 文档：分析代码库，审查 API 端点、参数和响应；按资源或端点组织参考内容并保持格式一致；为每个端点编写清晰描述、参数说明以及请求和响应示例；添加多语言代码示例；编写包含身份验证的快速入门指南；构建错误参考，记录错误码与排查方法；生成机器可读的 OpenAPI 规范。
-
用户指南创建：进行受众分析，识别用户画像与技能水平；梳理任务，列出所有用户任务与工作流；按用户旅程而非功能来组织内容大纲；编写带截图的逐步操作说明；补充上下文，解释为什么用以及何时用，而不只是怎么用；构建清晰的目录、索引和搜索关键词；用真实用户场景验证文档。
-
README 编写：用一段话概述项目做什么；提供包含前置条件的清晰安装说明；给出能快速跑起来的最小示例；提供带解释的真实代码用法示例；记录所有配置项、环境变量和参数标志；说明贡献指南与开发环境搭建；补充许可证与致谢等法律信息。
-
架构文档：提供高层系统概览与图示；拆解各主要组件及其职责；记录信息在系统中的流转方式；说明部署、扩展和监控方面的考量；描述安全模型，包括认证、授权和数据保护；记录架构决策及其理由。
使用方式
该技能通过自然语言触发词调用，常见操作包括：创建 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”）。
最佳实践
该技能强调：先讲“为什么”，在深入细节前解释用途与使用场景；每个概念都配可运行的代码示例；保持术语、格式和结构一致；面向快速浏览写作，多用标题、列表、表格和代码块；验证所有代码示例确实可用；清晰标注版本；随代码变更主动更新文档；有策略地链接相关内容；用图示表达复杂流程；优化可搜索性；提供使用时机与原因的上下文；记录常见错误及解决方案；使用简洁、易于翻译的语言以利于国际化；列出前置知识；让用户在 5 分钟内获得成功体验。
适用场景与限制
该技能适用于需要编写 API 文档、用户指南、README、教程、参考材料、架构文档、发布说明和迁移指南的开发与产品团队。关于该技能的具体收费、价格、支持平台或运行环境等信息，资料中暂未提供。