4.2 KiB
4.2 KiB
title, type, tags, date
| title | type | tags | date | |||
|---|---|---|---|---|---|---|
| Technical Writer Agent Personality | source |
|
2026-05-01 |
Source File
Summary（用中文描述）
- 核心主题：为 AI Agent 定义 Technical Writer（技术文档工程师）角色——将复杂工程概念转化为开发者真正愿意阅读的清晰、准确、引人入胜的文档。
- 问题域：开发者文档质量低下（代码无注释、文档过时、README 无法让开发者 30 秒内上手）、Docs-as-Code 基础设施建设不足。
- 方法/机制：
- 遵循 Divio 文档体系：教程 / 操作指南 / 参考文档 / 解释文档四象限分离
- Docs-as-Code 基础设施：Docusaurus、MkDocs、Sphinx、VitePress + CI/CD 集成
- API 文档：OpenAPI/Swagger 自动生成参考文档
- 质量门禁：代码示例必须测试通过，破坏性变更必须附带迁移指南
- 指标驱动：用 analytics、支持工单关联、用户反馈衡量文档有效性
- 结论/价值：技术文档是产品 bug；好文档能降低 20% 支持工单量，让新开发者 15 分钟内上手。
Key Claims（用中文描述）
- Technical Writer 必须在写文档前与工程师沟通：了解使用场景、难点、用户卡点
- README 必须通过"5 秒测试"：这是什么、为什么重要、如何开始
- 每个新功能必须附带文档——无文档的代码视为不完整
- 代码示例必须经过测试——每段代码在发布前必须验证可运行
- 文档必须与软件版本同步——旧版本文档要标注弃用而非删除
- 每个 API 必须有参考条目、至少一个代码示例和错误处理文档
- 高退出率页面 = 文档失败的信号
Key Quotes
"Bad documentation is a product bug — you treat it as such." — 核心理念：文档质量等同于产品质量
"Every new feature ships with documentation — code without docs is incomplete." — 质量门禁原则
"Zero broken code examples in any published doc" — 零错误代码示例标准
"Docs search satisfaction rate ≥ 80%" — 文档有效性核心指标
Key Concepts
- Divio Documentation System：将文档分为教程（学习导向）、操作指南（任务导向）、参考文档（信息导向）、解释文档（理解导向），不混用
- Docs-as-Code：将文档视为代码的一部分，通过 CI/CD 管道管理、版本控制和自动化构建
- API Documentation：从 OpenAPI/Swagger 规范自动生成参考文档，配合 Redoc/Stoplight 展示
- Technical Writer：内容工程师角色，专注于开发者文档架构与质量
Key Entities
- Docusaurus：Meta 出品的文档站点框架，基于 React
- MkDocs：Python 驱动的静态文档生成器，使用 Markdown
- Sphinx：Python 官方文档工具，支持多语言和丰富的扩展生态
- VitePress：Vue 团队出品的轻量级静态文档生成器
- OpenAPI/Swagger：API 规范标准，用于自动生成 API 参考文档
- Vale：开源 prose linter，用于文档风格检查
- Redoc：开源 API 文档渲染器，从 OpenAPI 规范生成文档
- Stoplight：商业 API 设计/文档平台
Connections
- Engineering Backend Architect ← writes_docs_for ← Technical Writer
- Engineering Code Reviewer ← reviews_docs ← Technical Writer
- Software Architect ← designs_architecture ← Technical Writer (provides docs requirements)
Contradictions
- 与 specialized-developer-advocate 冲突：
- 冲突点：技术写作与开发者倡导者都产出手册和教程，但目标受众和交付标准不同。
- 当前观点（Technical Writer）：文档以参考完整性优先，覆盖所有 API 端点和参数，面向不同熟练度的开发者分层提供内容。
- 对方观点（Developer Advocate）：教程必须先展示最终结果，必须包含失败模式和调试方法，代码必须零修改运行，不为非 GA 功能发布教程。
- 协调方案：Developer Advocate 负责"教程/快速入门/演示"等引导式内容；Technical Writer 负责"API 参考/规范文档/操作指南"等查阅式内容；两者共享 DX 反馈回路。