document-feature

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Document a feature — user-facing docs

为功能编写文档 —— 面向用户的文档

Write a feature page that a user (not a developer) can follow. Covers: what the feature does, why it exists, how to turn it on, how to use it, and where its boundaries are.

撰写一份可供用户（非开发者）遵循的功能页面。内容涵盖：功能用途、设计初衷、启用方法、使用步骤以及功能边界。

Before You Start

开始之前

The project's docs site root — common locations:

docs/

docs-site/

website/

, or a sibling

docs

package. Find it with

find . -maxdepth 3 -type f -name 'vitepress.config.*' -o -name 'docusaurus.config.*' -o -name 'mkdocs.yml'

A well-written existing feature page — read 1–2 to match voice and structure.
The feature's PR or design doc — the source of truth for behavior.
Any screenshots, diagrams, or demo videos attached to the feature's issue or PR.

If the project has no docs site, ask the user whether this documentation belongs in

README.md

, a dedicated

FEATURES.md

, or a new docs site entirely.

项目文档站点的根目录——常见位置：

docs/

、

docs-site/

、

website/

，或同级的

docs

包。可通过以下命令查找：

find . -maxdepth 3 -type f -name 'vitepress.config.*' -o -name 'docusaurus.config.*' -o -name 'mkdocs.yml'

。

一份写得较好的现有功能页面——阅读1-2份以匹配文档风格和结构。
功能对应的PR或设计文档——这是功能行为的权威来源。
功能相关issue或PR中附带的截图、图表或演示视频。

如果项目没有文档站点，请询问用户该文档应放在

README.md

、专门的

FEATURES.md

中，还是需要新建一个文档站点。

Step 1: understand the audience

步骤1：明确受众

Who reads this page? Usually one of:

End users — people who click the UI. They need: what does this do for me, how do I turn it on, what's the shortest path to value.
Administrators / operators — people who configure the system. They need: how to enable, permissions required, operational characteristics (latency, cost, failure modes).
Integrators — developers calling your API. They need: request/response shapes, auth, rate limits, migration path.

Each audience gets a different page shape. If the feature serves more than one, write separate pages or separate sections.

谁会阅读此页面？通常是以下人群之一：

终端用户：点击UI进行操作的用户。他们需要了解：此功能能为我带来什么？如何启用？最快获得价值的路径是什么？
管理员/运维人员：配置系统的人员。他们需要了解：如何启用、所需权限、运维特性（延迟、成本、故障模式）。
集成开发者：调用API的开发者。他们需要了解：请求/响应格式、认证方式、速率限制、迁移路径。

不同受众对应不同的页面结构。如果功能服务于多类受众，请编写单独页面或分章节说明。

Step 2: find the doc path convention

步骤2：确定文档路径规范

bash

ls docs/  # or docs-site/
find docs -type f -name '*.md' | head -20

Common patterns:

```
docs/features/<feature-name>.md
```
```
docs/guides/<feature-name>/index.md
```

Localized:

docs/<section>/<feature>/index.en.md

docs/<section>/<feature>/index.de.md

Versioned:
```
docs/v2/features/<feature>.md
```

Match the existing pattern exactly. Look at the file a user gets to from the docs site's navigation.

bash

ls docs/  # 或 docs-site/
find docs -type f -name '*.md' | head -20

常见模式：

```
docs/features/<feature-name>.md
```
```
docs/guides/<feature-name>/index.md
```

本地化：

docs/<section>/<feature>/index.en.md

、

docs/<section>/<feature>/index.de.md

版本化：
```
docs/v2/features/<feature>.md
```

严格匹配现有模式。参考文档站点导航中用户能访问到的文件路径。

Step 3: write the page

步骤3：撰写页面

Structure for an end-user feature page:

markdown

---
title: {Feature name — noun phrase}
description: {One-sentence summary that appears in search and social cards}
---

面向终端用户的功能页面结构：

markdown

---
title: {功能名称 —— 名词短语}
description: {一句话概述，将显示在搜索结果和社交卡片中}
---

{Feature name}

{功能名称}

{One-paragraph "what it is, why it exists." Anchored in a user problem: "If you want to X, this feature does Y." Not a technical description.}

{一段关于“是什么、为什么存在”的描述。围绕用户痛点展开：“如果你想要实现X，此功能可以帮你完成Y。”避免技术化描述。}

Prerequisites

前提条件

{Permissions or roles required}
{Subscription or plan required, if any}
{Other features that must be enabled first, with links}

{所需权限或角色}
{如需订阅或特定套餐，请注明}
{需提前启用的其他功能，并附上链接}

Enabling

启用步骤

{Step-by-step. Start from the most common entry point — usually the settings page or a CLI command. Use screenshots where they save words; otherwise use numbered steps with UI labels in bold.}

Open {Settings} → {Section}.
Toggle {Feature name} on.
Click Save.

{分步说明。从最常用的入口开始——通常是设置页面或CLI命令。能用截图简化说明的就用截图；否则使用带粗体UI标签的编号步骤。}

打开**{设置} → {对应板块}**。
开启**{功能名称}**的开关。
点击保存。

Using

使用方法

{Walk through the happy path. The user follows these steps and sees the feature work.}

{引导用户完成顺畅的操作流程，用户按照这些步骤操作即可看到功能生效。}

{Common task 1}

{常见任务1}

{Specific instruction, ending in an observable outcome.}

{具体操作说明，需明确可观察到的结果。}

{Common task 2}

{常见任务2}

{Another task.}

{另一项任务说明。}

Limits and boundaries

限制与边界

{Explicit list of what this feature does NOT do, rate limits, known caveats. Saves support tickets.}

{明确列出此功能不支持的操作、速率限制、已知注意事项。这能减少支持工单数量。}

Troubleshooting

故障排查

Symptom	Cause	Fix
{what the user sees}	{what went wrong}	{concrete action}

症状	原因	解决方法
{用户看到的现象}	{问题根源}	{具体解决操作}

Step 4: add the page to navigation

步骤4：将页面添加到导航

Docs sites require a manual nav entry — the file existing isn't enough. Find the nav config:

bash

undefined

文档站点需要手动添加导航条目——仅存在文件是不够的。找到导航配置：

bash

undefined

VitePress

cat docs/.vitepress/config.* | grep -A 10 "sidebar|nav"

Docusaurus

ls docs/sidebars* website/sidebars*

MkDocs

cat mkdocs.yml | grep -A 20 "nav:"


Add a line pointing at the new file in the right section.

cat mkdocs.yml | grep -A 20 "nav:"


在对应板块添加指向新文件的条目。

Step 5: generate or embed assets

步骤5：生成或嵌入资源

If the page needs screenshots or diagrams:

Screenshots: store in

docs/<feature>/images/

alongside the page. Naming:

{feature}-{step-or-state}.png

Diagrams: prefer Mermaid for anything the docs site renders natively (VitePress, Docusaurus do). SVG for complex diagrams. Avoid raster PNG exports of diagrams — they don't scale.

如果页面需要截图或图表：

截图：存储在页面同级目录的
```
docs/<feature>/images/
```
下。命名规则：
```
{feature}-{step-or-state}.png
```
。
图表：优先使用Mermaid（VitePress、Docusaurus可原生渲染）。复杂图表使用SVG。避免图表的PNG光栅导出——它们无法缩放。

Verify

验证

bash

undefined

bash

undefined

The page builds without broken links

页面构建无失效链接

(Run the docs site's build command from CLAUDE.md Quick Reference)

（从CLAUDE.md快速参考中运行文档站点的构建命令）

e.g. pnpm docs:build OR mkdocs build --strict OR yarn build

例如：pnpm docs:build 或 mkdocs build --strict 或 yarn build

The page appears in navigation

页面显示在导航中

Browse the rendered site and click through.

浏览渲染后的站点并点击验证。

Screenshots referenced by the page exist

页面引用的截图存在

grep -oE '![[^]]*]([^)]+)' <doc-path> | grep -oE '([^)]+)' | tr -d '()' | while read img; do [ ! -f "$(dirname <doc-path>)/$img" ] && echo "MISSING: $img" done

undefined

grep -oE '![[^]]*]([^)]+)' <doc-path> | grep -oE '([^)]+)' | tr -d '()' | while read img; do [ ! -f "$(dirname <doc-path>)/$img" ] && echo "MISSING: $img" done

undefined

Common Mistakes

常见错误

Mistake	Correction
Writing in developer voice ("This endpoint accepts a `User` object...")	Rewrite for the user. If the page is for integrators, it's a different page — use the API reference template.
Listing every setting without explaining which matter	Lead with the happy path (3–5 settings). Push exhaustive options into a "Reference" subsection or a separate page.
No troubleshooting section	Add one. Even "none that we know of" plus a contact/support link is better than silence.
Page exists but isn't in navigation	Users can't find it. Update the sidebar/nav file (step 4).

错误	修正方法
使用开发者口吻撰写（“此端点接受 `User` 对象……”）	为用户重新撰写。如果页面面向集成开发者，则属于不同类型的页面——使用API参考模板。
列出所有设置但不说明重要性	优先展示顺畅操作路径所需的3-5项设置。将详尽选项放到“参考”小节或单独页面。
无故障排查章节	添加该章节。即使是“暂无已知问题”加上联系/支持链接也比空白好。
页面存在但未加入导航	用户无法找到它。更新侧边栏/导航文件（步骤4）。

document-feature

Original

Translation

Document a feature — user-facing docs

为功能编写文档 —— 面向用户的文档

Before You Start

开始之前

Step 1: understand the audience

步骤1：明确受众

Step 2: find the doc path convention

步骤2：确定文档路径规范

Step 3: write the page

步骤3：撰写页面

{Feature name}

{功能名称}

Prerequisites

前提条件

Enabling

启用步骤

Using

使用方法

{Common task 1}

{常见任务1}

{Common task 2}

{常见任务2}

Limits and boundaries

限制与边界

Troubleshooting

故障排查

Related

相关链接

Writing discipline

写作准则

Step 4: add the page to navigation

步骤4：将页面添加到导航

VitePress

VitePress

Docusaurus

Docusaurus

MkDocs

MkDocs

Step 5: generate or embed assets

步骤5：生成或嵌入资源

Verify

验证

The page builds without broken links

页面构建无失效链接

(Run the docs site's build command from CLAUDE.md Quick Reference)

（从CLAUDE.md快速参考中运行文档站点的构建命令）

e.g. pnpm docs:build OR mkdocs build --strict OR yarn build

例如：pnpm docs:build 或 mkdocs build --strict 或 yarn build

The page appears in navigation

页面显示在导航中

Browse the rendered site and click through.

浏览渲染后的站点并点击验证。

Screenshots referenced by the page exist

页面引用的截图存在

Common Mistakes

常见错误