✏️ 写作风格

技术写作的 10 条规则、主动语态、短句、代码>文字、避免 jargon——让文档不说人话的根源在这里

📜 技术写作的 10 条规则

1 主动语态

✅ 主动

"The function returns a promise."
"Click the Submit button."
"The server sends a response."

❌ 被动

"A promise is returned by the function."
"The Submit button should be clicked."
"A response is sent by the server."

2 短句

每句不超过 25 个词。如果一个句子需要逗号+从句+修饰语才能说完，拆成两句。技术文档不是文学——清晰比优雅重要。

✅ 短句

"Create a new project. Run npm init. Then install the SDK."

❌ 长句

"After you have created a new project by running the npm init command in your terminal, you should then proceed to install the SDK by running the npm install command."

3 代码 > 文字

能用代码说清楚的，不要用文字。代码是精确的，文字是模糊的。一段 3 行代码示例胜过 3 段文字描述。

✅ 代码优先

// 获取用户列表
const users = await client.users.list({
  limit: 10,
  sort: 'created_at:desc'
});

❌ 文字描述

"To retrieve the list of users, you need to call the users endpoint with the list method, passing in a configuration object that specifies the limit parameter to control the number of results and the sort parameter to order by creation date in descending order."

4 避免 jargon

除非你的读者 100% 理解术语，否则用大白话。如果必须用 jargon，第一次出现时给出定义。

Jargon	大白话
idempotent	重复调用结果相同
serialization	把对象转成字符串
memoization	缓存函数结果
hydration	给静态页面加交互
reconciliation	对比新旧差异

5 第二人称

用"你"而不是"我们"或"用户"。文档是在和读者对话，不是在写报告。

✅ "你"

"你需要安装 Node.js 18+."
"你的 API Key 在 Settings 页面。"

❌ "用户"/"我们"

"用户需要安装 Node.js 18+."
"我们建议安装 Node.js 18+."

6 现在时

描述功能和行为时用现在时。不要用将来时——代码现在就能做，不是"将能做"。

✅ 现在时

"This function validates the input."
"The API returns a JSON response."

❌ 将来时

"This function will validate the input."
"The API will return a JSON response."

7 结构化

用标题、列表、表格组织内容。不要写大段落——没人读。每个段落一个主题，每个列表项一个要点。

8 一致性

同一个概念用同一个词。不要交替使用"API Key"和"Access Token"指同一件事。建立术语表。

9 精确

数字要精确，不要用"很多""很快""大概"。"支持 10,000 并发"比"支持高并发"好 10 倍。

10 可验证

每个断言都应该是可验证的。如果你说"性能提升 3x"，就要有 benchmark 代码让读者自己跑。

🇨🇳 中文技术写作的特殊注意点

中文技术文档有一些独特的挑战，是英文文档不需要面对的：

# 中文技术文档排版规范 ## 中英之间加空格 ✅ 使用 Node.js 18 运行此脚本 ❌ 使用Node.js18运行此脚本 ## 数字与中文之间加空格 ✅ 需要 3 个参数 ❌ 需要3个参数 ## 专有名词保持原文 ✅ Agent、Token、Embedding ❌ 代理、令牌、嵌入（翻译后更难理解） ## 代码保持英文标点 ✅ 调用 `getUser()` 方法 ❌ 调用 `getUser（）` 方法 ## 列表用项目符号，不用数字（除非有序） - 安装依赖 - 配置环境 - 运行测试 ## 自动格式化 # 安装 pangu npm install pangu # 或在 CI 中检查 npx pangu --check ./docs

📝 写作检查清单

# 每篇文档发布前检查 ## 内容 ☐ 是否有 Quick Start？ ☐ 代码块是否完整可运行？ ☐ 是否有预期输出示例？ ☐ 错误情况是否有说明？ ## 风格 ☐ 是否使用主动语态？ ☐ 句子是否短于 25 词？ ☐ 是否避免了 jargon（或给出定义）？ ☐ 是否使用"你"而非"用户"？ ## 排版（中文） ☐ 中英文之间是否有空格？ ☐ 标点符号是否统一？ ☐ 术语是否一致？ ## 技术 ☐ API 端点是否与 OpenAPI 文档一致？ ☐ 代码示例是否经过测试？ ☐ 版本号是否与当前发布一致？ ☐ 链接是否有效？ ## 可访问性 ☐ 图片是否有 alt 文本？ ☐ 颜色对比度是否足够？ ☐ 是否有纯文字版本的图表？

问题	说明	建议
中英混排	中英文之间不加空格很丑	使用 `pangu.js` 自动加空格
术语翻译	翻译还是不翻译？	常见词翻译（函数、变量），新词不翻译（Agent、Token）
标点符号	中文用全角，英文用半角	中文环境用中文标点，代码/英文用半角
代码注释	中文注释 vs 英文注释？	开源项目英文，内部项目中文，混合最差
排版	每个段落首行缩进？	技术文档不缩进，段间距分隔
"的"字过多	"用户的请求的处理的函数"	删掉多余"的"，或改用"之"

💡 Google Technical Writing Courses

Google 提供免费的 Technical Writing Courses，这是目前最好的技术写作入门课程。两个模块各约 2 小时，涵盖：清晰句子的写作、段落组织、文档结构、标点和格式。强烈推荐每位开发者完成。