67 lines
4.2 KiB
Markdown
67 lines
4.2 KiB
Markdown
---
|
||
title: "Technical Writer Agent Personality"
|
||
type: source
|
||
tags: ["agent-personality", "documentation", "developer-experience"]
|
||
date: 2026-05-01
|
||
---
|
||
|
||
## Source File
|
||
- [[Agent/agency-agents/engineering/engineering-technical-writer.md]]
|
||
|
||
## 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 反馈回路。
|