writing-web-documentation

编写 Web 文档

当用户希望为 Web 项目编写出色的技术文档，而不是只要“代码旁边配点文字”时，使用此技能。目标是编写易于入门、快速浏览、值得信赖且易于维护的文档。

好的文档不是产品事实的堆砌，而是引导读者围绕特定目标了解产品。

此技能的优化目标

1. 快速获得首次成功 新读者应能快速得到可用的结果。

2. 按意图清晰引导 学习产品的初学者和查询选项的专家，不应被迫面对同一页面。

3. 减少歧义 命令、文件名、版本、先决条件、预期结果和失败状态都应明确说明。

4. 便于快速浏览 开发者很忙，通常会先浏览再细读。标题、简介、列表、表格和代码块应让页面一目了然、易于导航。

5. 便于维护 文档应能随时间推移保持准确，易于随代码变更更新，并能让过时信息显而易见。

非目标

不要以以下目标为优化方向：

• 炒作
• 营销话术
• 每个页面都详述所有背景
• 在第一份文档中展示所有受支持的变体
• 花哨的文字
• 缺少说明的超长代码块

先决定：这是哪种页面？

选定页面类型后再开始起草。不同页面类型应明确区分。

README 或文档首页

用于介绍和引导。

• 回答：这是什么？面向谁？从哪里开始？
• 保持简短。
• 将深入细节放到子页面中。

快速入门

用于以最快的顺利路径获得可用结果。

• 一条路径。
• 一个主要环境。
• 尽量减少分支。
• 明确先决条件，并清楚展示成功状态。

教程

通过实践进行教学。

• 读者要构建有意义的内容。
• 包含检查点和回顾。
• 解释足以帮助学习的内容，但不必涵盖百科全书式的全部知识。

操作指南

用于解决一个具体问题。

• 假设读者已了解基础知识。
• 聚焦于结果，而非背景理论。

参考文档

用于回答具体的事实性问题。

• 语法、选项、默认值、参数、返回值、事件、错误、限制、兼容性。
• 内容简洁、完整且易于浏览。

说明／概念页面

用于帮助读者建立心智模型。

• 系统为何以这种方式工作。
• 架构、权衡、不变量、决策规则。
• 链接到相关任务文档和参考文档。

故障排除页面

根据症状诊断问题。

• 症状 -> 可能原因 -> 修复方法 -> 验证 -> 预防。

迁移指南

用于版本、API 或架构变更时。

• 明确说明会有哪些不兼容变更。
• 展示变更前后对比。
• 给出安全的操作顺序。
• 适用时提供回滚指导。

默认工作流

除非用户要求更具体的内容，否则请遵循此工作流。

1) 确定读者和目标

推断或说明：

• 读者类型：初学者、有经验的用户、维护者、集成者、API 使用者、平台工程师
• 任务：学习、设置、集成、自定义、调试、迁移、部署、贡献
• 环境：框架、运行时、包管理器、操作系统、浏览器、托管目标
• 成功状态：完成后读者应能做什么

如果缺少重要信息，不要无限期搁置。做出范围最小的合理假设，并明确标注。

2) 先盘点事实，再写正文

收集容易过时的事实：

• 包名
• 安装命令
• 运行时和框架版本
• 支持的浏览器或环境
• 环境变量
• URL、端点、端口、回调路径
• 权限、身份验证要求、密钥、令牌
• 构建、测试和部署命令
• 破坏性变更或限制

如果无法验证某项事实，不要凭空编造。使用明确标注的占位符或假设。

3) 先搭建页面骨架

在撰写完整段落之前，先搭建包含页面所需确切章节的骨架。

推荐顺序：

• 背景
• 前置条件
• 步骤或正文
• 验证 / 预期结果
• 后续步骤 / 相关页面

4) 以帮助读者首次成功运行为目标

每个任务页面都应帮助读者尽早取得一次成功结果。

这意味着：

• 优先展示最简可行路径
• 尽量减少分支
• 将高级选项留到后面
• 除非项目确实支持多个一流入口，否则优先选用一种包管理器和一种框架
• 展示成功后的效果

5) 确保示例可运行

示例应可直接复制粘贴，或易于调整。

• 使用真实文件名和合理的目录结构。
• 标注代码围栏的语言。
• 保持示例精简但完整。
• 仅在能消除歧义时添加注释。
• 如果命令具有破坏性或会产生费用，请先发出警告。
• 在重要步骤之后展示预期输出或可见结果。

6) 精简文字

完成草稿后：

• 缩短引言
• 拆分较长的段落
• 将含糊的标题改为基于任务的标题
• 删除重复说明
• 将理论内容移出流程页面
• 将详细内容移出着陆页

7) 按审查清单进行检查

交付前使用 assets/review-checklist.md。

参考文件

根据当前任务按需加载以下文件：

参考资料	用途
references/house-style.md	语气、句式、标题、篇幅目标、页面类型模式
references/web-project-rules.md	Web 项目检查清单、代码示例规则、反模式、无障碍、文档即代码
references/research-notes.md	对优秀文档网站和风格指南的研究综述

不要一次性加载所有文件。 只加载与当前任务相关的文件。

常见任务模式下的响应方式

被要求从头撰写页面时

交付：

1. 合适的页面类型
2. 润色后的 Markdown 草稿
3. 如有重要事实未知，清楚标明假设

被要求改进现有文档时

按以下顺序处理：

1. 判断当前页面类型
2. 删除混杂的内容模式
3. 精简结构
4. 改写以提升清晰度
5. 保留技术含义
6. 指出事实缺漏或内容过时的风险

被要求审查文档时

返回：

• 页面类型
• 按优先级排列的主要问题
• 明确的改写建议
• 缺少的章节
• 内容过时或可信度方面的问题

被要求设计文档网站时

返回：

• 受众群体
• 入口
• 所需页面类型
• 站点地图
• 编写优先级
• 缺口和风险

此技能中的文件

• assets/documentation-brief-template.md — 写作前收集事实
• assets/docs-ia-template.md — 规划文档站点或章节的结构
• assets/docs-home-template.md — 首页骨架
• assets/readme-template.md — README 骨架
• assets/quickstart-template.md — 快速上手指南
• assets/tutorial-template.md — 边做边学指南
• assets/how-to-template.md — 以任务为核心的指南
• assets/reference-template.md — API/参考文档骨架
• assets/explanation-template.md — 心智模型页面
• assets/troubleshooting-template.md — 从症状入手的故障排除指南
• assets/migration-guide-template.md — 升级/迁移页面
• assets/review-checklist.md — 最终质量检查
• references/house-style.md — 语气、篇幅目标和页面类型模式
• references/web-project-rules.md — Web 项目检查清单、代码规则和反模式
• references/research-notes.md — 这些规则的由来

最终说明

最好的文档页面读起来轻松，是因为作者为读者仔细斟酌了上百个选择：

• 哪些内容应放在此页面
• 哪些内容不应放在此页面
• 什么内容应放在前面
• 哪些内容应删去
• 哪些内容应核实
• 哪些内容应解释
• 哪些内容应留待以后

请审慎做出这些选择。