write-guide
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWriting Guides
技术指南撰写规范
Goal
目标
Produce a technical guide that teaches a real-world use case through progressive examples. Concepts are introduced only when the reader needs them.
Each guide solves one specific problem. Not a category of problems. If the outline has 5+ steps or covers multiple approaches, split it.
生成一份通过递进式示例教授实际用例的技术指南。仅在读者需要时才引入相关概念。
每份指南仅解决一个具体问题，而非一类问题。如果大纲包含5个及以上步骤或涵盖多种方法，请拆分内容。
Structure
结构
Every guide follows this arc: introduction, example setup, 2-5 progressive steps, next steps.
Each step follows this loop: working code → new requirement → friction → explanation → resolution → observable proof.
Sections: introduction (no heading, 2 paragraphs max), (what we're building + source link), (action-oriented titles, 2-4 steps), (summary + related links).
## Example### Step N## Next stepsHeadings should tell a story on their own. If readers only saw the headings, they'd understand the guide's takeaway.
每份指南都遵循以下脉络：引言、示例设置、2-5个递进步骤、后续步骤。
每个步骤遵循以下循环：可运行代码 → 新需求 → 问题点 → 解释 → 解决方案 → 可验证结果。
章节包括：引言（无标题，最多2段）、（说明我们要构建的内容+源码链接）、（动作导向的标题，2-4个步骤）、（总结+相关链接）。
## 示例### 步骤N## 后续步骤标题本身应能完整传达指南的核心内容。即使读者只看标题，也能理解指南的要点。
Template
模板
markdown
---
title: {Action-oriented, e.g., "Building X" or "How to Y"}
description: {One sentence}
nav_title: {Short title for navigation}
---
{What the reader will accomplish and why it matters. The friction and how this approach resolves it. 2 paragraphs max.}markdown
---
title: {动作导向，例如："构建X"或"如何实现Y"}
description: {一句话描述}
nav_title: {导航用短标题}
---
{说明读者将完成的内容及其重要性。阐述当前存在的问题以及本方案如何解决这些问题。最多2段。}Example
示例
As an example, we'll build {what we're building}.
We'll start with {step 1}, then {step 2}, and {step 3}.
{Source code link.}
作为示例，我们将构建{要构建的内容}。
我们将从{步骤1}开始，然后是{步骤2}，最后是{步骤3}。
{源码链接。}
Step 1: {Action-oriented title}
步骤1：{动作导向标题}
{Brief context, 1-2 sentences.}
tsx
// Minimal working code{Explain what happens.}
{Introduce friction: warning, limitation, or constraint.}
{Resolution: explain the choice, apply the fix.}
{Verify the fix with observable proof.}
{简要背景，1-2句话。}
tsx
// 最简可运行代码{解释代码的作用。}
{提出问题：警告、限制或约束。}
{解决方案：解释选择的原因，应用修复方案。}
{通过可验证结果确认修复效果。}
Step 2: {Action-oriented title}
步骤2：{动作导向标题}
{Same pattern: context → code → explain → friction → resolution → proof.}
{遵循相同模式：背景 → 代码 → 解释 → 问题 → 解决方案 → 验证结果。}
Step 3: {Action-oriented title}
步骤3：{动作导向标题}
{Same pattern.}
{遵循相同模式。}
Next steps
后续步骤
You now know how to {summary}.
Next, learn how to:
- Related guide 1
- Related guide 2
undefined你现在已经掌握了{总结内容}。
接下来，你可以学习：
- 相关指南1
- 相关指南2
undefinedWorkflow
工作流程
- Research: Check available skills for relevant features. Read existing docs for context and linking opportunities.
- Plan: Outline sections. Verify scope (one problem, 2-4 steps). Each step needs a friction point and resolution.
- Write: Follow the template above. Apply the rules below.
- Review: Re-read the rules, verify, then present.
- 调研：查阅现有技能文档中的相关功能。阅读现有文档以获取上下文并寻找关联链接的机会。
- 规划：列出章节大纲。确认范围（仅一个问题，2-4个步骤）。每个步骤都需要有一个问题点和对应的解决方案。
- 撰写：遵循上述模板。应用以下规则。
- 审核：重新阅读规则，进行验证，然后提交。
Rules
规则
- Progressive disclosure. Start with the smallest working example. Introduce complexity only when the example breaks. Name concepts at the moment of resolution, after the reader has felt the problem. Full loop: working → new requirement → something breaks → explain why → name the fix → apply → verify with proof → move on.
- Show problems visually. Console errors, terminal output, build warnings, slow-loading pages. "If we refresh the page, we can see the component blocks the response."
- Verify resolutions with observable proof. Before/after comparisons, browser reloads, terminal output. "If we refresh the page again, we can see it loads instantly."
- One friction point per step. If a step has multiple friction points, split it.
- Minimal code blocks. Only the code needed for the current step. Collapse unchanged functions with .
function Header() {} - No em dashes. Use periods, commas, or parentheses instead.
- Mechanical, observable language. Describe what happens, not how it feels.
- No selling, justifying, or comparing. No "the best way," no historical context, no framework comparisons.
| Don't | Do |
|---|---|
| "creates friction in the pipeline" | "blocks the response" |
| "needs dynamic information" | "depends on request-time data" |
| "requires dynamic processing" | "output can't be known ahead of time" |
| "The component blocks the response — causing delays" | "The component blocks the response. This causes delays." |
- 递进式信息披露：从最小的可运行示例开始。仅当示例出现问题时才引入复杂概念。在读者遇到问题后，也就是解决方案环节再命名相关概念。完整流程：可运行 → 新需求 → 出现问题 → 解释原因 → 给出解决方案名称 → 应用方案 → 验证结果 → 进入下一步。
- 直观展示问题：比如控制台错误、终端输出、构建警告、页面加载缓慢。例如：“如果我们刷新页面，可以看到组件阻塞了响应。”
- 通过可验证结果确认解决方案：使用前后对比、浏览器刷新、终端输出等方式。例如：“如果我们再次刷新页面，可以看到页面瞬间加载完成。”
- 每个步骤仅一个问题点：如果一个步骤包含多个问题点，请拆分步骤。
- 精简代码块：仅保留当前步骤所需的代码。用折叠未修改的函数。
function Header() {} - 不使用破折号：改用句号、逗号或括号。
- 使用客观、可观察的表述：描述实际发生的情况，而非主观感受。
- 不进行推销、辩解或对比：不使用“最佳方式”，不提及历史背景，不进行框架对比。
| 错误示例 | 正确示例 |
|---|---|
| "creates friction in the pipeline" | "blocks the response" |
| "needs dynamic information" | "depends on request-time data" |
| "requires dynamic processing" | "output can't be known ahead of time" |
| "The component blocks the response — causing delays" | "The component blocks the response. This causes delays." |
References
参考资料
Read these guides in before writing. They demonstrate the patterns above.
docs/01-app/02-guides/- — intro → example → 3 progressive steps → next steps. Concepts named at point of resolution. Problems shown with build output.
public-static-pages.mdx - — progressive feature building without explicit "Step" labels. Each section adds one capability.
forms.mdx
在撰写前，请阅读目录下的以下指南，它们展示了上述模式。
docs/01-app/02-guides/- — 引言 → 示例 → 3个递进步骤 → 后续步骤。在解决方案环节命名相关概念。通过构建输出来展示问题。
public-static-pages.mdx - — 逐步构建功能，无明确的“步骤”标签。每个章节新增一项功能。
forms.mdx