technical-writer

技术文档作者

专注于开发者文档、API 参考、系统架构文档、运行手册和知识库文章的技术文档专家。

快速入门

1. 确定文档类型，使用 Diátaxis：教程、操作指南、说明或参考
2. 了解受众——他们了解什么、需要完成什么
3. 从结构入手——先列提纲，再开始撰写；使用模板
4. 提供可运行的示例——所有代码都必须经过测试且可运行
5. 添加故障排除内容——预判常见问题
6. 验证完整性——链接有效、步骤准确、不遗漏任何假设

核心能力

文档类型	目的	主要特点
教程	以学习为导向	动手实践、循序渐进地介绍
操作指南	以任务为导向	解决具体问题
说明	以理解为导向	背景、上下文、概念
参考	以信息为导向	准确、完整、易于搜索

Diátaxis 框架

              PRACTICAL                    THEORETICAL
        ┌──────────────────────┬──────────────────────┐
LEARNING│     TUTORIALS        │    EXPLANATIONS      │
        │  "Learning by doing" │  "Understanding why" │
        ├──────────────────────┼──────────────────────┤
WORKING │    HOW-TO GUIDES     │     REFERENCE        │
        │  "Solve problems"    │  "Look up facts"     │
        └──────────────────────┴──────────────────────┘

参考模板

完整模板位于 ./references/：

模板	用途
readme-template.md	包含所有必要部分的项目 README
adr-template.md	架构决策记录
api-reference-template.md	REST API 文档
runbook-template.md	运维流程

反模式（10 个关键错误）

1. 大段文字

症状：段落密集，没有标题或视觉间隔
解决方法：使用标题、项目符号、表格、代码块和留白

2. 过时的示例

症状：代码示例无法编译或使用已弃用的 API
解决方法：在 CI 中测试所有示例，锁定依赖版本，添加“最后验证”日期

3. 缺少前置条件

症状：教程假定读者具备某些知识或已完成设置，却未明确说明
解决方法：提前列出前置条件，链接到设置指南，注明版本

4. 专家盲点

症状：省略了对初学者而言并不显而易见的“显而易见”步骤
解决方法：请新手测试文档，列出所有步骤，解释“为什么”

5. 缺少错误处理指引

症状：只介绍顺利流程，没有故障排除内容
解决方法：列出常见错误及解决方案，链接到支持渠道

6. 链接失效

症状：链接指向已迁移或已删除页面，导致 404
解决方法：在 CI 中检查链接，尽可能使用相对链接，为已迁移内容设置重定向

7. 格式不一致

症状：样式、代码块语言和标题级别各不相同
解决方法：制定样式指南，使用 lint 工具（markdownlint），为常见文档类型提供模板

8. 缺少上下文

症状：文档假定读者了解系统架构
解决方法：在开头简要介绍上下文，链接到架构文档，说明“这部分内容的作用”

9. 截图过时

症状：界面截图比当前版本落后三个版本
解决方法：自动截取屏幕截图，注明界面版本，优先使用文字而非图片

10. 没有版本管理

症状：文档与用户安装的版本不匹配
解决方法：添加版本选择器和版本徽章，并按主要版本维护文档

质量检查清单

结构：

• 遵循 Diátaxis 框架（教程／操作指南／说明／参考）
• 适合目标受众的水平
• 格式和风格一致
• 更新目录

内容：

• 代码示例经过测试且可运行
• 所有链接均有效（没有 404）
• 在适当位置注明版本信息
• 包含故障排除部分

完整性：

• 提前列出前置条件
• 包含所有步骤（避免专家盲点）
• 涵盖错误场景
• 链接到相关文档

验证脚本

运行 ./scripts/validate-docs.sh 以检查：

• README 完整性
• 文档结构
• ADR 格式合规性
• 失效链接
• 常见文档问题

文档工具

静态站点：Docusaurus、MkDocs、VitePress、Astro
API 文档：Swagger/Redoc、Stoplight、ReadMe.io
图表：Mermaid、PlantUML、Excalidraw、Diagrams.net

外部资源

• Diátaxis 框架
• Google 开发者文档风格指南
• Write the Docs
• Keep a Changelog
• ADR GitHub