technical-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical Writing

技术写作

Write clear, consistent technical documentation based on Google's developer documentation style guide.

基于谷歌开发者文档风格指南编写清晰、统一的技术文档。

Core Principles

核心原则

Clarity over cleverness: Prioritize understandable prose over elegant writing
Consistency matters: Apply rules uniformly throughout a document
Audience-first: Write for developers with varying English proficiency

清晰优先于巧思：优先保证行文易懂，而非辞藻华丽
一致性很重要：在整篇文档中统一应用所有规则
以受众为中心：面向英语水平各异的开发者写作

Voice and Tone

语气与风格

Use second person: Address the reader directly with "you."

Good: "You can configure the server by editing

config.yaml

." Bad: "We can configure the server by editing

config.yaml

Use active voice: Make clear who performs the action.

Good: "The function returns an error code." Bad: "An error code is returned by the function."

Be conversational but professional: Write naturally without slang, jargon, or excessive formality. Use common contractions like "you're," "don't," and "it's" to maintain an informal tone.

使用第二人称：直接用「你」称呼读者。

正确示例："You can configure the server by editing

config.yaml

." 错误示例："We can configure the server by editing

config.yaml

使用主动语态：明确说明动作的执行者。

正确示例："The function returns an error code." 错误示例："An error code is returned by the function."

对话感但保持专业：行文自然，不使用俚语、行话或过于正式的表达。可使用常见的缩写如 "you're"、"don't"、"it's" 来保持轻松的语气。

What to Avoid

注意规避

Jargon and buzzwords: "leverage," "utilize," "synergy"
Filler phrases: "please note that," "it should be noted"
Exclamation marks: Reserve for genuinely exciting moments
Implying simplicity: "simply," "just," "easy" (frustrates struggling readers)
Latin abbreviations: Write "for example" not "e.g.", "that is" not "i.e."
Directional language: Use "earlier/later" not "above/below"
Anthropomorphic language: Don't attribute human qualities to software ("the system wants," "the server thinks")
Skipping articles: Always include "a," "an," and "the"—even in headings

行话和热词："leverage"、"utilize"、"synergy"
填充语："please note that"、"it should be noted"
感叹号：仅在真正值得兴奋的场景使用
暗示内容简单："simply"、"just"、"easy"（会让遇到困难的读者感到沮丧）
拉丁语缩写：写 "for example" 而非 "e.g."，写 "that is" 而非 "i.e."
方位性表述：使用「前文/后文」而非「上面/下面」
拟人化表述：不要给软件赋予人类属性（如「系统想要」、「服务器认为」）
省略冠词：始终添加 "a"、"an" 和 "the"——即使在标题中也不例外

Inclusive Language

包容性语言

Avoid	Use Instead
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

避免使用	推荐使用
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

Capitalization

大小写规则

Sentence case for headings: Capitalize only the first word and proper nouns
Product names: Always capitalize (Tenzir, Kubernetes, Docker)
Acronyms: Use standard capitalization (API, HTTP, JSON)

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

Headings

标题规范

Task headings: Use bare infinitives ("Create an instance")
Concept headings: Use noun phrases ("User authentication")
Hierarchy: Don't skip levels (h1 to h3 without h2)
No links: Avoid hyperlinks within headings

任务类标题：使用动词原形（如 "Create an instance"）
概念类标题：使用名词短语（如 "User authentication"）
层级结构：不要跳过标题层级（不要直接从h1跳到h3而跳过h2）
不要加链接：避免在标题内添加超链接

Lists

列表规范

Numbered lists: For sequential steps or ordered items.

Bulleted lists: For non-sequential items.

List guidelines:

Introduce with a complete sentence followed by a colon
Start each item with a capital letter
Use parallel structure across items
End with periods if items contain verbs or are complete sentences
Don't use single-item lists

有序列表：用于连续步骤或有顺序的条目。

无序列表：用于非连续的条目。

列表通用规则：

列表前使用完整句子加冒号引入
每个条目首字母大写
所有条目使用平行结构
如果条目包含动词或为完整句子，末尾加句号
不要使用单条目的列表

Procedures

操作步骤规范

Structure:

Introduce with context
Number each step
Start steps with imperative verbs
State location before action

Guidelines:

"In the Settings panel, click Save." (location before action)
Mark optional steps with "Optional:" at the start
Document one accessible procedure, not multiple alternatives
Avoid "please" in instructions

结构：

先介绍上下文背景
给每个步骤编号
步骤以祈使动词开头
先说明位置，再说明操作

规则：

"在设置面板中，点击保存。"（位置先于操作）
可选步骤开头标注「可选：」
只提供一种可访问的操作步骤，不要罗列多个替代方案
操作说明中避免使用「请」

Code in Text

文本中的代码

Use code font (backticks) for:

Command-line input and output
Filenames and paths
Class, method, and function names
Keywords, variables, and parameters
HTTP status codes and methods

Don't use code font for:

Product names and services
URLs meant to be followed in a browser
Domain names

Grammar: Don't inflect code elements. Write "send a

POST

request" not "

POST

the data."

以下场景使用代码字体（反引号包裹）：

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

以下场景不要使用代码字体：

产品名称与服务
供浏览器访问的URL
域名

语法规则：不要对代码元素进行词形变化。写 "send a

POST

request" 而非 "

POST