technical-writing（技术写作）

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.

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

Inclusive Language

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)

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

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:

1. Introduce with context
2. Number each step
3. Start steps with imperative verbs
4. 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."

Word Choices

Formatting

• UI elements: Bold (File > Save)
• User input: Code font or bold, depending on context
• New terms: Italics on first use
• Emphasis: Use sparingly; prefer restructuring sentences

Links

• Use descriptive link text that makes sense out of context
• Avoid "click here" or "this page"
• Good: "See the authentication guide."
• Bad: "Click here for more information."

Reference Hierarchy

When style questions arise, consult in order:

1. Project-specific guidelines
2. Google Developer Documentation Style Guide
3. Merriam-Webster (spelling)
4. Chicago Manual of Style (general)
5. Microsoft Writing Style Guide (technical)