technical-writing

技术写作

遵循 Google 开发者文档风格指南，撰写清晰、一致的技术文档。

核心原则

• 清晰优先于巧妙：优先使用易懂的文字，而非优雅的写法
• 保持一致很重要：在整篇文档中统一应用规则
• 以受众为先：面向英语水平各不相同的开发者撰写

语态和语气

使用第二人称：直接用“你”称呼读者。

好：“你可以通过编辑 config.yaml 来配置服务。” 不好：“我们可以通过编辑 config.yaml 来配置服务。”

使用主动语态：明确说明由谁执行操作。

好：“该函数会返回错误代码。” 不好：“错误代码由该函数返回。”

语气自然、专业：自然表达，避免俚语、行话或过度正式。使用“you're”“don't”和“it's”等常见缩写，保持轻松的语气。

避免以下内容

• 行话和流行语：“利用”“使用”“协同效应”
• 填充语：“请注意”“应该注意”
• 感叹号：仅在确实令人兴奋时使用
• 暗示操作简单：“只需”“轻松”“简单”（会让遇到困难的读者感到沮丧）
• 拉丁语缩写：写“例如”，不要写“e.g.”；写“也就是说”，不要写“i.e.”
• 方向性表述：使用“较早/较晚”，不要使用“上方/下方”
• 拟人化表述：不要赋予软件人类特质（“系统想要”“服务认为”）
• 省略冠词：始终包含“a”“an”和“the”，标题中也不例外

包容性语言

避免使用	改用
blacklist/whitelist	denylist/allowlist、blocklist/safelist
master/slave	primary/replica、leader/follower
man-hours	person-hours
guys	everyone、folks、team
sanity check	quick check、coherence check

大小写

• 标题使用句首字母大写格式：仅首词和专有名词首字母大写
• 产品名称：始终大写（Tenzir、Kubernetes、Docker）
• 缩略词：使用标准大小写（API、HTTP、JSON）

标题

• 任务标题：使用动词原形（“创建实例”）
• 概念标题：使用名词短语（“用户身份验证”）
• 层级：不要跳过层级（从 h1 直接跳到 h3，跳过 h2）
• 不要使用链接：避免在标题中加入超链接

列表

编号列表：用于连续步骤或有序项目。

项目符号列表：用于非连续项目。

列表指南：

• 先用完整句子引出列表，并以冒号结尾
• 每个项目以大写字母开头
• 各项目使用平行结构
• 如果项目包含动词或构成完整句子，以句号结尾
• 不要使用仅含一项的列表

操作步骤

结构：

1. 提供背景说明
2. 为每个步骤编号
3. 每个步骤以祈使动词开头
4. 先说明位置，再说明操作

指南：

• “在 Settings 面板中，点击 Save。”（先说明位置，再说明操作）
• 在可选步骤开头标注“可选：”
• 记录一种易于访问的操作流程，不要提供多个备选方案
• 指令中避免使用“请”

正文中的代码

以下内容使用代码字体（反引号）：

• 命令行输入和输出
• 文件名和路径
• 类、方法和函数名称
• 关键字、变量和参数
• HTTP 状态码和方法

以下内容不要使用代码字体：

• 产品名称和服务
• 用于在浏览器中访问的 URL
• 域名

语法：不要对代码元素进行词形变化。写“发送一个 POST 请求”，不要写“POST 数据”。

用词

避免	改用
aka	also known as，或使用括号
allows you to	lets
config	configuration
admin	administrator
click on	click
check（复选框）	select
uncheck	clear
higher/lower（版本）	later/earlier

格式

• UI 元素：加粗（File > Save）
• 用户输入：根据上下文使用代码字体或粗体
• 新术语：首次出现时使用斜体
• 强调：谨慎使用；优先通过调整句子结构来表达

链接

• 使用脱离上下文也易于理解的描述性链接文本
• 避免使用“点击此处”或“此页面”
• 推荐：“请参阅身份验证指南。”
• 不推荐：“点击此处了解更多信息。”

参考资料优先级

遇到风格问题时，按以下顺序参考：

1. 项目专属指南
2. Google 开发者文档风格指南
3. Merriam-Webster（拼写）
4. Chicago Manual of Style（通用规范）
5. Microsoft 写作风格指南（技术规范）