Back to Details

technical-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical writing

技术写作

Write accurate, task-focused documentation for developers and coding agents. Each section should be easy to scan, retrieve, and act on without unstated context.
为开发者和 coding Agent 编写准确、以任务为中心的技术文档。每个章节都应便于浏览、检索和执行，不依赖未说明的上下文。

Consuming repo

使用此 skill 的仓库

Read the repo's 
AGENTS.md
before you write: doc layers, public one-liner, capability names, banned copy, and where 
DESIGN.md
lives. Glob rules in 
.cursor/rules/
override this skill. For which layer to update (MDX vs README vs rules), use 
/w-docs
—do not duplicate its routing table here.
开始编写前，先阅读仓库的 
AGENTS.md
：了解文档层级、公开定位语、能力名称、禁用文案以及 
DESIGN.md
的位置。
.cursor/rules/
中的 Glob 规则优先于此 skill。要更新哪个文档层级（MDX、README 或 rules），使用 
/w-docs
；不要在此重复其路由表。

Voice

语气

  • Address the reader as 
    you
    ; use imperative verbs for steps. Active voice, present tense, concrete nouns.
  • American English, Oxford comma. Write 
    eve
    lowercase when naming the runtime.
  • Lead each page and section with the answer or outcome. One primary job per page.
  • Preserve the author's supported meaning, nuance, and uncertainty. Make the minimum effective edit; leave strong prose alone.
  • Use 
    we
    only when describing a deliberate team action documented in the repo.
Ban filler and hype: 
easy
, 
simple
, 
quick
, 
just
, 
obviously
, 
utilize
, 
facilitate
, 
leverage
, 
robust
, 
seamless
, promotional adjectives, rhetorical questions, engagement bait.
Ban AI tells: summary transitions (
With this setup complete…
), stop-start fragments, datasheet verbs (
provides
, 
is configurable
), cold opens with no antecedent, template closers and closing proverbs, manufactured specificity to sound human.
Cadence. Bad: "The API is flexible. It supports many use cases. That is the value. You will like it." Good: "Register the route in 
apps/api
, expose it in OpenAPI, then run the client generator so the web app picks up typed calls."
  • 使用 
    you
    称呼读者；步骤中使用祈使动词。采用主动语态、现在时和具体名词。
  • 使用美式英语和牛津逗号。指代 runtime 时，将 
    eve
    写为小写。
  • 每个页面和章节都应以答案或结果开头。每个页面只承担一项主要任务。
  • 保留作者有依据的含义、细微差异和不确定性。进行最小且有效的编辑；不要改动优质文本。
  • 仅在描述仓库中有明确记录的团队行动时使用 
    we
    。
禁止填充词和炒作词：
easy
、
simple
、
quick
、
just
、
obviously
、
utilize
、
facilitate
、
leverage
、
robust
、
seamless
、促销性形容词、反问句和互动诱导语。
禁止 AI 写作痕迹：总结式过渡语（
With this setup complete…
）、断断续续的片段、数据表式动词（
provides
、
is configurable
）、没有前文的冷开场、模板化结尾和说教式收尾，以及为了显得像人而刻意制造具体细节。
句子节奏。不佳示例：“The API is flexible. It supports many use cases. That is the value. You will like it.” 良好示例：“Register the route in 
apps/api
, expose it in OpenAPI, then run the client generator so the web app picks up typed calls.”

Sources of truth

事实来源

Do not rely on training data for behavior. Verify in this order:
  1. Owning source, public types, and tests in the repo
  2. CLI help and package scripts named in the nearest README
  3. Existing MDX or markdown in the doc layer 
    AGENTS.md
    names
  4. ADRs and architecture pages—proposed intent until merged behavior matches
  5. Issues and user reports—to learn the reader's problem, not to establish product truth
If a claim cannot be verified, omit it or name the missing owner. Never leave 
[VERIFY]
in finished copy. Do not document proposed behavior as shipped.
不要依赖训练数据判断行为。按以下顺序验证：
  1. 仓库中负责该行为的源代码、公共类型和测试
  2. 最近的 README 中明确提到的 CLI 帮助和 package scripts
  3. AGENTS.md
    指定的文档层级中已有的 MDX 或 Markdown
  4. ADR 和架构页面——在合并后的行为与之匹配前，仅代表拟议意图
  5. Issues 和用户报告——用于了解读者的问题，而非认定产品事实
如果某项声明无法验证，请省略该声明，或指出缺少负责方。完成后的文案中不得保留 
[VERIFY]
。不要将拟议行为描述为已发布的行为。

Method

方法

  1. Name the piece's one job and the reader's task.
  2. Find the page that already owns the topic; extend it before creating a new page.
  3. Outline: outcome → prerequisites → happy path → alternatives → failures → related links.
  4. Draft and verify claims together against source.
  5. Self-edit for retrieval: repeat full nouns in key statements; put the critical fact locally, not only behind a link.
  6. Review passes: purpose and structure, accuracy, completeness, style and retrieval, diff discipline (no drive-by rewrites).
  1. 明确文档的唯一目的以及读者要完成的任务。
  2. 查找已经负责该主题的页面；优先扩展现有页面，而不是新建页面。
  3. 拟定大纲：结果 → 前置条件 → 正常路径 → 替代方案 → 失败处理 → 相关链接。
  4. 起草时同步对照源代码验证声明。
  5. 从便于检索的角度自审：在关键声明中重复使用完整名词；将关键事实直接写入当前页面，而不是只放在链接后。
  6. 分轮审查：目的与结构、准确性、完整性、风格与可检索性，以及 diff 纪律（不做顺带重写）。

Modes

模式

Docu MDX (when the repo has 
apps/docu/content/docs/
): 
title
and 
description
frontmatter; folder 
meta.json
when navigation changes; inbound body link from a related hub (no orphan pages); permanent redirects in doc app config when a route moves; MDX components only where nearby pages already use them. Finish with 
pnpm --filter @repo/docu checktypes
when preparing to ship doc changes.
README (
**/README.md
): follow 
.cursor/rules/base/readme.mdc
—root owns the product story; apps and packages stay lean with links to technical docs.
Root product markdown (e.g. 
PRODUCT.md
, 
ARCHITECTURE.md
, 
DESIGN.md
when 
AGENTS.md
says so): same voice; capability names match that repo's architecture source; upstream hosted docs win only where 
AGENTS.md
says they override local project docs.
Docu MDX（仓库包含 
apps/docu/content/docs/
时）：设置 
title
和 
description
frontmatter；导航发生变化时更新文件夹的 
meta.json
；从相关 hub 页面建立正文入站链接（不得产生孤立页面）；路由迁移时，在文档应用配置中添加永久重定向；仅在附近页面已经使用 MDX 组件时才引入这些组件。准备交付文档变更时，最后运行 
pnpm --filter @repo/docu checktypes
。
README（
**/README.md
）：遵循 
.cursor/rules/base/readme.mdc
——根目录 README 负责产品定位；应用和 package 的 README 保持精简，并链接到技术文档。
根目录产品 Markdown（例如 
PRODUCT.md
、
ARCHITECTURE.md
，以及 
AGENTS.md
指定的 
DESIGN.md
）：采用相同语气；能力名称与仓库的架构来源保持一致；仅当 
AGENTS.md
明确说明上游托管文档优先于本地项目文档时，才遵循该优先级。

Constraints

约束

  • NEVER invent flags, endpoints, defaults, examples, metrics, or user reactions.
  • NEVER turn one support thread into a new page without deciding docs vs product scope.
  • NEVER duplicate a broad guide when a section or cross-link fixes the gap.
  • NEVER contradict the consuming repo's public one-liner, banned copy, or capability names for narrative convenience.
  • Support evidence identifies confusion; implementation and tests establish behavior.
  • 绝不虚构 flags、endpoints、defaults、示例、指标或用户反应。
  • 在决定属于文档问题还是产品范围问题之前，绝不将单个支持线程扩展为新页面。
  • 当补充章节或交叉链接即可解决缺口时，绝不重复编写宽泛指南。
  • 不得为了叙事方便而违背使用此 skill 的仓库所定义的公开定位语、禁用文案或能力名称。
  • 支持性证据用于识别困惑；实现和测试用于确定行为。

Not this skill

不属于此 skill

  • /w-docs
    — which layer to patch
  • /w-api-docs
    — OpenAPI and generated clients
  • /w-deslop
    — code slop on branches
  • /w-architecture
    — ADR and boundary planning
  • Personal or marketing voice catalogs (e.g. gabo)
  • /w-docs
    ——判断应更新哪个文档层级
  • /w-api-docs
    ——OpenAPI 和生成的客户端
  • /w-deslop
    ——清理分支上的代码废话
  • /w-architecture
    ——ADR 和边界规划
  • 个人或营销语气目录（例如 gabo）