Update nexus wiki content

wiki/sources/engineering-technical-writer.md

@@ -0,0 +1,66 @@
+---
+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 反馈回路。