Back to Details

writing-user-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

User-facing documentation

面向用户的文档

Write for the person using the tool, not the person who built it.
"User" means whoever uses the thing. For an app, that's an end user. For a library, it's the developer who installs it. Either way they are not implementing it, and the docs should reflect that.
为使用工具的人而写，而不是为构建工具的人而写。
“用户”指使用该工具的任何人。对于应用而言，就是最终用户；对于库而言，就是安装该库的开发者。无论哪种情况，他们都不是在实现它，文档也应体现这一点。

Voice

语气

Everyday English — the way you'd explain it to a colleague sitting next to you. Formality doesn't add authority, it just adds distance and words.
  • Second person, active, present tense. "You tap Save," not "the Save button should be tapped" or "the user will then be able to save."
  • Cut "just," "simply," "easy," "obviously." They add nothing when things work, and read as mockery when they don't.
  • No marketing adjectives. "Powerful," "seamless," "robust," "intuitive" — that's the author admiring the product. The reader is mid-task and doesn't care.
  • One term per concept, matching the UI exactly. If the button says Workspace, the docs never say "project" or "team space." Varying your vocabulary is good prose and bad documentation — every synonym reads as a new concept.
日常英语——就像你会向坐在旁边的同事解释那样。正式不会增添权威感，只会拉开距离、徒增字数。
  • 使用第二人称、主动语态和现在时。 “你点按 Save”，而不是“应该点按 Save 按钮”或“用户随后将能够保存”。
  • 删掉“just”“simply”“easy”“obviously”。 它们在一切正常时不提供任何信息，出错时读起来却像是在嘲弄读者。
  • 不要使用营销形容词。 “Powerful”“seamless”“robust”“intuitive”——这些是在表达作者对产品的欣赏。读者正在完成任务，并不在意这些。
  • 每个概念只使用一个术语，并与 UI 完全一致。 如果按钮显示 Workspace，文档中就绝不写“project”或“team space”。变换词汇在文章中或许是好文笔，在文档中却是坏习惯——每个同义词看起来都像一个新概念。

Scope: what goes in

范围：应包含什么

Include only what the reader needs to use the tool. The default is to leave things out.
Implementation details stay out. Not the database, the queue, the framework, the algorithm's name, the internal service, the refactor it took to ship. The test isn't "is this technical?" — it's "will the reader be surprised, or make a wrong decision, without it?"
Observable behavior passes that test even when it sounds technical, and belongs in the docs: rate limits, offline behavior, what syncs and when, where files are stored, what happens on a conflict, what survives a reinstall. The machinery producing that behavior doesn't.
Concise means no filler, not short. Every sentence earns its place. A thorough troubleshooting section is still concise if none of it is padding — and a two-line page is bloated if one line is a welcome message. Cut preambles, restatements of the heading, and "in this article you will learn."
只包含读者使用工具所需的内容。默认做法是省略不必要的内容。
实现细节不应写入。 不要写数据库、队列、框架、算法名称、内部服务，或为发布产品所做的重构。判断标准不是“这是不是技术内容？”，而是：“缺少这些内容，读者会不会感到意外，或作出错误决定？”
即使听起来技术性，只要属于可观察行为，也应写入文档：速率限制、离线行为、哪些内容会同步以及何时同步、文件存放在哪里、发生冲突时会怎样、重新安装后哪些内容会保留。产生这些行为的内部机制则不应写入。
简洁意味着没有废话，而不是篇幅短。 每个句子都应有自己的作用。只要没有填充内容，详尽的故障排查章节仍然可以很简洁；反过来，如果两行页面中有一行只是欢迎语，那么它仍然是臃肿的。删掉开场白、重复标题的内容，以及“本文你将了解……”之类的话。

Structure

结构

  • Organize by user goal, not by feature or screen. Headings are things people want to do — "Share a report with someone outside your team" — not nouns like "Sharing module."
  • Lead with the outcome, then the steps. People need to know they're on the right page before investing in step 1.
  • Prerequisites and limits go up front. Required plan, permission, platform, file size cap. Discovering the blocker at step 6 is the worst possible moment.
  • One page answers one question, and stands alone. Most readers arrive from search or a deep link, never from page 1. Assume no one read the previous page; link instead of assuming.
  • Pick one path. Where three ways exist, document the recommended one. Alternatives get a short note at the end, or nothing.
  • 按用户目标组织，而不是按功能或界面组织。 标题应描述人们想完成的事情——例如“与团队外的人共享报告”——而不是“共享模块”之类的名词短语。
  • 先说明结果，再给出步骤。 人们需要先确认自己找对了页面，然后才会投入执行步骤 1。
  • 前置条件和限制放在开头。 所需的套餐、权限、平台、文件大小上限。让人到步骤 6 才发现阻碍因素，是最糟糕的情况。
  • 一个页面回答一个问题，并能独立阅读。 大多数读者来自搜索或深层链接，而不是从第 1 页开始阅读。不要假定读者读过上一页；应提供链接，而不是作此假设。
  • 只选择一条路径。 如果有三种方式，文档推荐的方式。其他方式在末尾用简短说明提及，或者干脆不写。

Cover the unhappy path

覆盖失败场景

This is the most-skipped section and the one people actually search for.
  • Document the failure cases: what the error says, what causes it, what to do next.
  • Say what the feature doesn't do when users predictably assume it does. Cheaper than a support ticket.
  • Warn before destructive actions, never after. The warning goes above the step it applies to.
这是最常被略过、却最常被用户搜索的部分。
  • 记录失败情况：错误提示是什么、原因是什么、下一步该怎么做。
  • 当用户很可能会误以为某项功能具备某项能力时，应明确说明它不做什么。 这比处理一张支持工单更省成本。
  • 破坏性操作之前必须警告，绝不能放在之后。 警告应置于相应步骤上方。

Keep it from rotting

防止内容过时

  • Real examples with real-looking data. No 
    foo
    , no 
    test123
    , no lorem ipsum. Examples should be copy-pasteable and produce the result shown.
  • No time-relative language. "New," "recently," "currently," "coming soon" — all rot silently. So do roadmap promises.
  • Walk every procedure literally. If someone following it word-for-word can't finish, the doc is wrong — not the reader.
  • 使用真实示例和看似真实的数据。 不要使用 
    foo
    、
    test123
    或 lorem ipsum。示例应可直接复制粘贴，并产生所示结果。
  • 不要使用与时间相关的表述。 “New”“recently”“currently”“coming soon”都会悄悄过时，路线图承诺也是如此。
  • 逐字走查每个操作流程。 如果有人完全按照说明操作仍无法完成，那么错的是文档，而不是读者。

Before publishing

发布前

Read the draft once looking only for these:
  1. Anything the reader doesn't need to finish the task → cut it.
  2. Anything about how it works internally → cut it, unless behavior depends on it.
  3. Any sentence you wouldn't say out loud → rewrite it.
  4. What happens when this goes wrong → is that answered?
只针对以下问题将草稿通读一遍：
  1. 读者完成任务不需要的任何内容 → 删掉。
  2. 关于内部工作原理的任何内容 → 删掉，除非具体行为依赖于此。
  3. 任何你不会当面说出的句子 → 改写。
  4. 出错时会发生什么 → 是否已经回答？