Back to Details

writing-web-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing web documentation

编写Web文档

Use this skill when the user wants excellent technical documentation for a web project, not merely "some text around the code." The job is to produce documentation that is easy to enter, easy to scan, easy to trust, and easy to maintain.
Good documentation is not a dump of product facts. It is a guided path through the product for a reader with a specific goal.
当用户需要为Web项目提供优质的技术文档，而不仅仅是“代码周边的零散文字”时使用本技能。本技能的目标是产出易入门、易浏览、可信、易维护的文档。
好的文档不是产品信息的堆砌，而是为有明确目标的读者提供的产品使用引导路径。

What this skill optimizes for

本技能的优化方向

  1. Fast first success A new reader should reach a working result quickly.
  2. Clear routing by intent A beginner learning the product and an expert checking an option should not have to fight the same page.
  3. Low ambiguity Commands, file names, versions, prerequisites, expected outcomes, and failure states should be explicit.
  4. Scannability Busy developers skim before they read. Headings, intros, lists, tables, and code blocks should make the page navigable at a glance.
  5. Maintenance Docs should age gracefully, be easy to update with code changes, and make stale information obvious.
  1. 快速初次成功 新读者应该能快速获得可运行的结果。
  2. 按用户意图清晰分流 学习产品的新手和查询选项的专家不需要在同一个页面里费力寻找信息。
  3. 低歧义 命令、文件名、版本、前置条件、预期结果和故障状态都应该明确说明。
  4. 易浏览性 忙碌的开发者在通读前会先略读。标题、导语、列表、表格和代码块应该让页面一目了然，易于导航。
  5. 易维护性 文档应该能平稳迭代，随代码变更轻松更新，并且让过时信息显而易见。

Non-goals

非目标

Do not optimize for:
  • hype
  • marketing language
  • exhaustive background on every page
  • showing every supported variation in the first document
  • clever prose
  • giant code dumps with little explanation
不要为以下内容优化：
  • 炒作宣传
  • 营销话术
  • 每个页面都堆砌详尽的背景信息
  • 在第一篇文档里展示所有支持的变体
  • 花哨的行文
  • 几乎没有解释的大量代码堆砌

First decide: what kind of page is this?

首先确定：这是什么类型的页面？

Never draft before choosing the page type. Keep page types distinct.
选择页面前永远不要先起草内容。保持页面类型的独立性。

README or docs landing page

README或文档落地页

Use for orientation and routing.
  • Answer: What is this? Who is it for? Where do I start?
  • Keep it short.
  • Push deep detail into child pages.
用于定位和导航。
  • 回答：这是什么？适用人群？我该从哪里开始？
  • 保持简洁
  • 把深度细节放到子页面中

Quickstart

快速入门

Use for the fastest happy path to a working result.
  • One path.
  • One main environment.
  • Minimal branching.
  • Clear prerequisites and a visible success state.
用于提供最快的可运行结果的最优路径。
  • 单一路径
  • 单个核心环境
  • 最少的分支流程
  • 明确的前置条件和清晰的成功状态

Tutorial

教程

Use to teach by doing.
  • The reader builds something meaningful.
  • Include checkpoints and a recap.
  • Explain enough for learning, not enough for encyclopedia coverage.
用于通过实践教学。
  • 读者会构建出有实际意义的内容
  • 包含检查点和回顾
  • 解释足够支撑学习即可，不需要做到百科全书式的覆盖

How-to guide

操作指南

Use to solve one concrete problem.
  • Assumes the reader already knows the basics.
  • Focus on outcome, not background theory.
用于解决一个具体的问题。
  • 假设读者已经掌握基础知识
  • 聚焦结果，而非背景理论

Reference

参考页

Use to answer precise factual questions.
  • Syntax, options, defaults, parameters, return values, events, errors, limits, compatibility.
  • Dry, complete, easy to scan.
用于回答精确的事实性问题。
  • 语法、选项、默认值、参数、返回值、事件、错误、限制、兼容性
  • 严谨、完整、易浏览

Explanation / concept page

说明/概念页

Use to build mental models.
  • Why the system works this way.
  • Architecture, trade-offs, invariants, decision rules.
  • Link outward to task docs and reference docs.
用于构建心智模型。
  • 系统为什么按照这种方式运行
  • 架构、取舍、不变量、决策规则
  • 外链到任务文档和参考文档

Troubleshooting page

故障排查页

Use to diagnose problems by symptom.
  • Symptom -> likely cause -> fix -> verify -> prevention.
用于根据症状诊断问题。
  • 症状 -> 可能原因 -> 修复方案 -> 验证 -> 预防

Migration guide

迁移指南

Use when versions, APIs, or architecture change.
  • Make breakage explicit.
  • Show before/after.
  • Give a safe order of operations.
  • Include rollback guidance when relevant.
用于版本、API或架构变更的场景。
  • 明确说明破坏性变更
  • 展示变更前后的对比
  • 给出安全的操作顺序
  • 相关场景下包含回滚指导

The default workflow

默认工作流

Follow this workflow unless the user asks for something narrower.
除非用户要求更窄的范围，否则遵循以下工作流：

1) Identify the reader and job

1) 确定读者和任务

Infer or state:
  • reader type: beginner, experienced user, maintainer, integrator, API consumer, platform engineer
  • task: learn, set up, integrate, customize, debug, migrate, deploy, contribute
  • environment: framework, runtime, package manager, OS, browser, hosting target
  • success state: what the reader should be able to do after finishing
If any important fact is missing, do not block forever. Make the narrowest reasonable assumption and label it clearly.
推断或明确：
  • 读者类型：新手、有经验的用户、维护者、集成者、API消费者、平台工程师
  • 任务：学习、搭建、集成、定制、调试、迁移、部署、贡献
  • 环境：框架、运行时、包管理器、操作系统、浏览器、部署目标
  • 成功状态：读者完成阅读后应该能完成什么操作
如果缺失任何重要信息，不要一直阻塞。做出最合理的窄范围假设并明确标注。

2) Inventory facts before prose

2) 行文前先整理事实点

Collect the facts that often go stale:
  • package names
  • install commands
  • runtime and framework versions
  • supported browsers or environments
  • environment variables
  • URLs, endpoints, ports, callback paths
  • permissions, auth requirements, keys, tokens
  • build, test, and deploy commands
  • breaking changes or constraints
If you cannot verify a fact, avoid inventing it. Use a clearly marked placeholder or assumption.
收集容易过时的事实信息：
  • 包名
  • 安装命令
  • 运行时和框架版本
  • 支持的浏览器或环境
  • 环境变量
  • URL、端点、端口、回调路径
  • 权限、认证要求、密钥、令牌
  • 构建、测试和部署命令
  • 破坏性变更或约束
如果你无法验证某个事实，不要编造。使用明确标记的占位符或假设。

3) Build the page skeleton first

3) 先搭建页面骨架

Before writing full paragraphs, create a skeleton with the exact sections the page needs.
Preferred order:
  • context
  • prerequisites
  • steps or body
  • verification / expected result
  • next steps / related pages
在写完整段落之前，先创建包含页面所需确切章节的骨架。
推荐顺序：
  • 上下文
  • 前置条件
  • 步骤或正文
  • 验证/预期结果
  • 后续步骤/相关页面

4) Write for the first successful run

4) 为首次成功运行而写作

Every task page should help the reader get one successful outcome as early as possible.
That means:
  • front-load the shortest working path
  • minimize branching
  • postpone advanced options
  • prefer one package manager and one framework unless the project truly supports several first-class entry points
  • show what success looks like
每个任务页面都应该帮助读者尽可能早地获得一个成功结果。
这意味着：
  • 把最短的可用路径放在最前面
  • 最小化分支流程
  • 延后介绍高级选项
  • 优先选择一个包管理器和一个框架，除非项目确实支持多个一流入口点
  • 展示成功的状态是什么样的

5) Make examples runnable

5) 让示例可运行

Examples should be copy-pasteable or easy to adapt.
  • Use real filenames and realistic directories.
  • Label code fences.
  • Keep examples minimal but complete.
  • Add comments only where they remove ambiguity.
  • If a command is destructive or billable, warn first.
  • Show expected output or visible result after important steps.
示例应该可以直接复制粘贴或者很容易适配。
  • 使用真实的文件名和符合实际的目录结构
  • 给代码块标注类型
  • 保持示例最小但完整
  • 只在消除歧义的地方添加注释
  • 如果命令具有破坏性或会产生费用，提前警告
  • 在重要步骤后展示预期输出或可见结果

6) Tighten the prose

6) 精简行文

After the draft exists:
  • shorten intros
  • split long paragraphs
  • convert vague headings into task-based headings
  • remove duplicated explanation
  • move theory out of procedural pages
  • move detail out of landing pages
草稿完成后：
  • 缩短导语
  • 拆分长段落
  • 把模糊的标题改成基于任务的标题
  • 删除重复的解释
  • 把理论内容从流程页面移出
  • 把细节内容从落地页移出

7) Run the review checklist

7) 运行审核检查清单

Use 
assets/review-checklist.md
before delivering.
交付前使用
assets/review-checklist.md
核查。

Reference files

参考文件

Load these on demand based on current task:
ReferencePurpose
references/house-style.mdVoice, sentence style, headings, length targets, page-type patterns
references/web-project-rules.mdWeb-project checklists, code example rules, anti-patterns, accessibility, docs-as-code
references/research-notes.mdResearch synthesis from strong documentation sites and style guides
DO NOT load all files at once. Load only what's relevant to your current task.
根据当前任务按需加载：
参考文件用途
references/house-style.md表述风格、句式风格、标题、长度目标、页面类型规范
references/web-project-rules.mdWeb项目检查清单、代码示例规则、反模式、无障碍、docs-as-code
references/research-notes.md来自优质文档站点和风格指南的研究总结
不要一次性加载所有文件。 只加载与当前任务相关的内容。

How to respond in common task modes

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

When asked to write a page from scratch

当被要求从零开始写一个页面时

Deliver:
  1. the appropriate page type
  2. a polished Markdown draft
  3. clearly marked assumptions if any important facts are unknown
交付：
  1. 合适的页面类型
  2. 完善的Markdown草稿
  3. 如果有未知的重要事实，明确标注假设

When asked to improve existing docs

当被要求优化现有文档时

Do this in order:
  1. identify the current page type
  2. remove mixed modes
  3. tighten structure
  4. rewrite for clarity
  5. preserve technical meaning
  6. call out factual gaps or staleness risks
按以下顺序执行：
  1. 确定当前页面类型
  2. 移除混合模式
  3. 收紧结构
  4. 重写以提升清晰度
  5. 保留技术含义
  6. 标注事实缺口或过时风险

When asked to review docs

当被要求审核文档时

Return:
  • the page type
  • the top issues in priority order
  • exact rewrite suggestions
  • missing sections
  • any staleness or trust issues
返回：
  • 页面类型
  • 按优先级排序的核心问题
  • 准确的重写建议
  • 缺失的章节
  • 任何过时或可信度问题

When asked to design a docs site

当被要求设计一个文档站点时

Return:
  • audience segments
  • entry points
  • page types needed
  • sitemap
  • priority order for authoring
  • gaps and risks
返回：
  • 受众细分
  • 入口点
  • 所需页面类型
  • 站点地图
  • 创作优先级顺序
  • 缺口和风险

Files in this skill

本技能包含的文件

  • assets/documentation-brief-template.md
    — collect facts before writing
  • assets/docs-ia-template.md
    — structure a docs site or section
  • assets/docs-home-template.md
    — landing page skeleton
  • assets/readme-template.md
    — README skeleton
  • assets/quickstart-template.md
    — happy-path setup guide
  • assets/tutorial-template.md
    — learning-by-doing guide
  • assets/how-to-template.md
    — task-focused guide
  • assets/reference-template.md
    — API/reference skeleton
  • assets/explanation-template.md
    — mental-model page
  • assets/troubleshooting-template.md
    — symptom-first troubleshooting
  • assets/migration-guide-template.md
    — upgrade/migration page
  • assets/review-checklist.md
    — final quality gate
  • references/house-style.md
    — voice, length targets, page-type patterns
  • references/web-project-rules.md
    — web-project checklists, code rules, anti-patterns
  • references/research-notes.md
    — why these rules exist
  • 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
    — 规则来源说明

Final instruction

最终说明

The best documentation pages feel easy because the writer made a hundred careful choices for the reader:
  • what belongs on this page
  • what does not
  • what comes first
  • what to cut
  • what to verify
  • what to explain
  • what to defer
Make those choices deliberately.
最好的文档页面之所以用起来轻松，是因为作者为读者做了上百次谨慎的选择：
  • 哪些内容属于这个页面
  • 哪些内容不属于
  • 哪些内容放在前面
  • 哪些内容要删掉
  • 哪些内容要验证
  • 哪些内容要解释
  • 哪些内容要延后说明
请有意识地做出这些选择。