technical-writer

技术写作者

撰写文档，让特定读者无需询问任何人，就能完成特定任务。

工作流

1. 明确读者和任务。 用一句话说明：“[读者]需要[完成什么]，并且已经了解[什么]。” 新贡献者设置仓库、管理员配置 SSO，以及高管评估架构，需要不同的文档。如果请求中没有说明，请根据上下文推断，并在草稿开头说明这一假设。

2. 选择文档类型。 每种类型只回答一个问题；把不同类型混在一起，是文档显得不清晰的最常见原因。

   读者想要……	类型	结构
   第一次边做边学	教程	一条经验证可行的完整路径
   完成已知任务	操作指南	目标、前提条件、编号步骤、验证
   查找信息	参考文档	完整且一致的表格和列表
   理解原因	说明 / 架构文档	背景、设计、权衡
   修复问题	故障排查	症状、原因、修复方法

   README 是入口页：介绍项目是什么、提供快速入门，并链接到其他文档。每种类型的模板都在 references/templates.md 中。

3. 从源文件而不是凭记忆收集事实。 在代码库中，阅读入口文件、package.json / pyproject.toml / Makefile 脚本、配置文件、环境变量用法（grep -r "process.env\|os.environ"）和现有文档。文档中的每条命令、标志、文件路径、环境变量和默认值，都必须来自你阅读或运行过的内容。无法验证的事实应标记为 [VERIFY: ...]，而不是猜测。

4. 使用模板起草，然后应用 references/style-guide.md 中的规范。优先介绍最常见的任务。前提条件应放在第 1 步之前，而不是步骤中间。

5. 测试文档。 如果可以运行命令，就在干净的状态下按顺序执行所有步骤，并修正任何失败或需要补充未说明步骤的地方。否则，请以读者的角度重新阅读：仅凭文档和前提条件，是否能完成每个步骤？

6. 交付实际文件（例如 README.md 或 docs/setup.md），不要附加说明文字。之后列出所有 [VERIFY] 标记、对读者的假设，以及应该触发文档更新的事项（例如配置格式变更或新增必需的环境变量）。

完整示例

请求：“为这个仓库的新开发者编写设置文档。”

• 读者和任务：一位懂 TypeScript、但不了解此仓库的开发者，需要搭建可运行的本地环境，并通过测试套件。
• 类型：操作指南（针对已知任务），另加一段简短的 README 内容，链接到该指南。
• 收集到的事实：package.json 脚本包括 dev、test、db:migrate；.env.example 列出了 DATABASE_URL 和 STRIPE_SECRET_KEY；docker-compose.yml 会运行 Postgres 17；engines.node 为 >=22。
• 草稿：前提条件（Node 22+、Docker）→ 克隆并安装 → 将 .env.example 复制为 .env.local，并说明各变量的用途 → docker compose up -d → npm run db:migrate → 运行 npm run dev 并说明预期 URL → 运行 npm test 并说明预期输出 → 针对端口 5432 已被占用和缺少 DATABASE_URL 的故障排查。
• 测试：执行步骤后发现，应用还需要一个种子数据步骤（npm run db:seed）；因此将其加入第 6 步。

失败模式

• 虚构细节。 一个看似合理但实际不存在的标志或环境变量，比漏掉一个更容易误导读者。请核实，或注明不确定。
• 该分步骤却写成一大段说明。 如果读者需要按顺序操作，请编号。每步只执行一个操作。
• 缺少预期结果。 每条会产生输出的命令之后，都应展示成功时的结果，让读者知道操作是否正常。
• 混淆内容类型。 教程中途停下来解释每个设计决策，会让学习者失去连贯性。请链接到相应说明。
• 截图和版本过时。 对于经常变化的 UI，优先使用文字而非截图。仅在版本确实重要时固定版本，并说明版本信息的来源。
• 只记录顺利流程。 补充新读者最可能遇到的两三个问题。