Back to Details

writing-for-a-technical-audience

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing for a Technical Audience

面向技术受众的写作

Overview

概述

Core principle: Technical writing must be clear, concise, and authentic. Clarity and technical depth are not opposites - you can have both. Avoid AI writing patterns that make content feel robotic or inauthentic.  Why this matters: Developers value their time. Clear documentation builds trust. AI-like writing patterns (identified through research) make content feel generic and untrustworthy. Technical depth without clarity frustrates users. Clarity without depth leaves them stuck.
核心原则： 技术写作必须清晰、简洁且真实。清晰性与技术深度并非对立关系——二者可以兼得。避免使用会让内容显得机械、不真实的AI写作模式。
重要性： 开发者十分珍惜时间。清晰的文档能建立信任。经研究发现，类AI写作模式会让内容显得通用且不可信。缺乏清晰性的技术深度会让用户受挫，而缺乏深度的清晰性则会让用户陷入困境。

When to Use

适用场景

Use this skill when:
  • Writing API documentation or references
  • Creating guides, tutorials, or how-to content
  • Documenting code, features, or architecture
  • Writing technical blog posts or articles
  • Reviewing technical content for clarity
Trigger symptoms:
  • "Does this sound too robotic?"
  • Writing feels formal or stiff
  • Using phrases like "delve into" or "leverage"
  • Explaining obvious things instead of getting to the point
  • Uncertain if content is clear enough
在以下场景使用本技巧：
  • 撰写API文档或参考资料
  • 创建指南、教程或操作类内容
  • 记录代码、功能或架构
  • 撰写技术博客文章
  • 审核技术内容的清晰度
触发信号：
  • “这听起来是不是太机械了？”
  • 写作风格正式生硬
  • 使用“delve into”或“leverage”这类短语
  • 解释显而易见的内容而非直奔主题
  • 不确定内容是否足够清晰

The Three Pillars

三大支柱

1. Clarity

1. 清晰性

Developers should understand on first read. No re-reading required.
Techniques:
  • Short sentences (15-20 words average)
  • Short paragraphs (2-4 sentences)
  • Active voice over passive
  • One concept per paragraph
  • Define technical terms on first use
开发者应能一读就懂，无需反复阅读。
技巧：
  • 短句（平均15-20词）
  • 短段落（2-4句）
  • 使用主动语态而非被动语态
  • 每段只讲一个概念
  • 首次出现的技术术语需定义

2. Conciseness

2. 简洁性

Every word serves a purpose. Remove noise and filler.
Techniques:
  • Delete throat-clearing ("Let me explain," "It's important to note")
  • Cut hedging language ("basically," "generally speaking")
  • Remove marketing fluff ("powerful," "robust," "seamless")
  • Use direct language ("use" not "leverage," "show" not "illuminate")
每个词都要有存在的意义。去除冗余和填充内容。
技巧：
  • 删除铺垫性语句（如“Let me explain,” “It's important to note”）
  • 去掉模糊性措辞（如“basically,” “generally speaking”）
  • 删除营销话术（如“powerful,” “robust,” “seamless”）
  • 使用直接表述（用“use”而非“leverage”，用“show”而非“illuminate”）

3. Consistency

3. 一致性

Same terminology, structure, and voice throughout.
Techniques:
  • Pick one term and stick to it (not "endpoint," "URL," "route" interchangeably)
  • Use consistent code formatting
  • Maintain same tone across all content
  • Follow established patterns for similar content types
全程使用统一的术语、结构和语气。
技巧：
  • 选定一个术语并坚持使用（不要交替使用“endpoint,” “URL,” “route”）
  • 使用统一的代码格式
  • 所有内容保持相同语气
  • 同类内容遵循既定模式

Avoid AI Writing Patterns

避免AI写作模式

Research shows specific phrases and structures that readers identify as AI-generated. Avoid these to maintain authenticity.
研究表明，读者能通过特定短语和结构识别出AI生成内容。为保持真实性，请避免使用这些模式。

AI Phrases to Never Use

绝对不要使用的AI短语

AI PhraseWhy It's BadUse Instead
"delve into"Overly formal, 269x spike post-ChatGPT"explore," "examine," "look at"
"leverage"Corporate jargon"use," "take advantage of"
"robust" / "seamless"Vague marketing adjectivesBe specific about what you mean
"at its core"Condescending simplification"fundamentally" (use rarely) or delete
"cutting-edge" / "revolutionary"Empty hypeDescribe actual features
"streamline" / "optimize"Vague promises"speed up," "reduce," "improve"
"foster" / "cultivate"Bland corporate speakUse direct action verbs
"unlock the potential"Cliched metaphorState specific outcome
"in today's fast-paced world"Generic fillerDelete entirely
"needless to say"If needless, don't say itDelete
AI短语问题所在替代表述
"delve into"过于正式，ChatGPT出现后使用量激增269倍"explore," "examine," "look at"
"leverage"企业行话"use," "take advantage of"
"robust" / "seamless"模糊的营销形容词具体说明你的意思
"at its core"带有 condescension的简化表述偶尔使用"fundamentally"或直接删除
"cutting-edge" / "revolutionary"空洞的炒作描述实际功能
"streamline" / "optimize"模糊的承诺"speed up," "reduce," "improve"
"foster" / "cultivate"平淡的企业用语使用直接的动作动词
"unlock the potential"陈腐的比喻说明具体成果
"in today's fast-paced world"通用填充语直接删除
"needless to say"既然没必要说，就别说删除

Throat-Clearing to Delete

需要删除的铺垫性语句

Never start with:
  • "Let me explain..."
  • "It's important to note that..."
  • "It's worth noting..."
  • "In essence..."
  • "Let's explore..."
Fix: Start with substance. Delete the preamble.
绝对不要以以下内容开头：
  • "Let me explain..."
  • "It's important to note that..."
  • "It's worth noting..."
  • "In essence..."
  • "Let's explore..."
修正方法： 直接切入正题，删除铺垫。

Hedging Language to Eliminate

需要消除的模糊性措辞

HedgedConfident
"I think we should...""We should..."
"It would be great if...""Please do X"
"Should be able to...""Can complete..."
"Basically..."Delete it
"Generally speaking..."Be specific or remove
"One might argue...""This indicates..."
Why hedging fails: Makes you sound uncertain even when you're correct. State facts directly.
模糊表述明确表述
"I think we should...""We should..."
"It would be great if...""Please do X"
"Should be able to...""Can complete..."
"Basically..."删除
"Generally speaking..."具体化或删除
"One might argue...""This indicates..."
模糊表述的问题： 即使你是对的，也会让你听起来不确定。直接陈述事实。

Transition Word Overuse

过度使用的过渡词

AI defaults to formal Victorian-era connectors. Use simpler alternatives or break paragraphs.
Overused AIBetter
Moreover / FurthermorePlus, also, and
However / NeverthelessBut, though, still
AdditionallyAnd, plus
Consequently / As a resultSo, then
That being saidBut (or delete)
Indeed / InterestinglyOften delete entirely
In conclusionEnd cleanly without announcing it
AI默认使用正式的维多利亚时代风格连接词。使用更简单的替代词或拆分段落。
过度使用的AI过渡词更好的选择
Moreover / FurthermorePlus, also, and
However / NeverthelessBut, though, still
AdditionallyAnd, plus
Consequently / As a resultSo, then
That being saidBut（或删除）
Indeed / Interestingly通常直接删除
In conclusion干净收尾，无需提前宣告

Technical Writing Patterns

技术写作模式

Explain WHY for These Cases

这些情况需要解释原因

ALWAYS explain why when:
  1. Design decisions with tradeoffs
    • Good: "We use pagination instead of cursors because it's simpler for most use cases and maintains consistent ordering"
    • Bad: "We use pagination" (no context for when to deviate)
  2. Non-obvious patterns
    • Good: "Row Level Security must be enabled on all tables exposed via the Data API because it enforces security at the database level, preventing bypass through direct SQL access"
    • Bad: "Enable RLS on all tables" (why?)
  3. Breaking from conventions
    • Good: "This API uses POST for reads because GET requests can't include request bodies in some HTTP clients"
    • Bad: "Use POST to fetch data" (violates REST conventions without justification)
When "how" alone suffices:
  • Mechanical steps with no alternatives ("Click Save")
  • Standard practices ("Use npm install")
  • When you genuinely don't know why (document behavior, note uncertainty)
在以下场景必须解释原因：
  1. 存在权衡的设计决策
    • 优秀示例：“我们使用分页而非游标，因为它对大多数使用场景来说更简单，且能保持一致的排序”
    • 糟糕示例：“我们使用分页”（没有说明何时可以例外的上下文）
  2. 非显而易见的模式
    • 优秀示例：“所有通过Data API暴露的表必须启用Row Level Security，因为它在数据库层面强制执行安全策略，防止通过直接SQL访问绕过限制”
    • 糟糕示例：“在所有表上启用RLS”（没有说明原因）
  3. 打破常规的做法
    • 优秀示例：“本API使用POST进行读取操作，因为部分HTTP客户端不支持在GET请求中包含请求体”
    • 糟糕示例：“使用POST获取数据”（违反REST规范却未说明理由）
只需说明操作方法的场景：
  • 无替代方案的机械步骤（如“点击保存”）
  • 标准实践（如“使用npm install”）
  • 你确实不知道原因的情况（记录行为，注明不确定性）

Code Examples: One Excellent Example

代码示例：一个优秀的示例就足够

Don't:
  • Implement in 5 languages
  • Create fill-in-the-blank templates
  • Write perfect-world examples with no error handling
Do:
  • One complete, runnable example
  • Include error handling
  • Show realistic usage
  • Comment WHY, not what
Good Example Pattern:
python
undefined
不要：
  • 用5种语言实现
  • 创建填空式模板
  • 编写无错误处理的理想化示例
要：
  • 一个完整、可运行的示例
  • 包含错误处理
  • 展示真实使用场景
  • 注释说明原因，而非内容
优秀示例模式：
python
undefined

Good: Complete, realistic, explains why

Good: Complete, realistic, explains why

try: response = await fetch_user(user_id) # Check status before assuming success - API returns 200 for "not found" if response.status != 200: raise APIError(f"Failed to fetch user: {response.status}") return response.json() except NetworkError as e: # Network failures are retryable - log and re-raise for retry logic logger.warning(f"Network error fetching user {user_id}: {e}") raise

**Bad Example Pattern:**

```python
try: response = await fetch_user(user_id) # Check status before assuming success - API returns 200 for "not found" if response.status != 200: raise APIError(f"Failed to fetch user: {response.status}") return response.json() except NetworkError as e: # Network failures are retryable - log and re-raise for retry logic logger.warning(f"Network error fetching user {user_id}: {e}") raise

**糟糕示例模式：**

```python

Bad: Perfect world, no context, brittle

Bad: Perfect world, no context, brittle

response = await fetch_user(user_id) return response.json()
undefined
response = await fetch_user(user_id) return response.json()
undefined

Progressive Disclosure

渐进式披露

Layer complexity. Simple first, then depth.
Pattern:
  1. Basic explanation - what it does, core concept
  2. Simple example - minimal working code
  3. Advanced section - edge cases, configuration, tradeoffs
  4. Reference - complete API surface
Good:
markdown
undefined
分层呈现复杂度。先展示简单内容，再深入细节。
模式：
  1. 基础说明 - 功能、核心概念
  2. 简单示例 - 最简可运行代码
  3. 高级部分 - 边缘情况、配置、权衡
  4. 参考资料 - 完整API范围
优秀示例：
markdown
undefined

Authentication

身份验证

All API requests require an API key in the Authorization header:
bash
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/users
所有API请求都需要在Authorization头中携带API密钥：
bash
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/users

Advanced: Token Rotation

高级：令牌轮换

For production systems, rotate API keys every 90 days...

**Bad:**
```markdown
对于生产系统，每90天轮换一次API密钥...

**糟糕示例：**
```markdown

Authentication

身份验证

Authentication can be performed using several methods including API keys, OAuth 2.0, or JWT tokens. The choice depends on your security requirements, user experience goals, and architectural constraints. Let's explore each option...

(Too much upfront. Start simple.)
身份验证可通过多种方法实现，包括API密钥、OAuth 2.0或JWT令牌。选择取决于你的安全要求、用户体验目标和架构约束。让我们逐一探索每个选项...

（前期信息过多。从简单内容开始。）

Anti-Patterns from Real Documentation

真实文档中的反模式

1. Assumes Too Much

1. 假设用户了解过多内容

Bad:
"Simply connect your ETLOrchestrator to the HydraNode endpoint. Once a connection is established, instantiate a DataStream by passing your KinesisConfiguration."
Why it fails: Jargon firehose with no definitions, no links, no onramp for beginners.
Fix: Define terms, link to prerequisites, provide Getting Started guide.
糟糕示例：
“只需将你的ETLOrchestrator连接到HydraNode端点。建立连接后，通过传入KinesisConfiguration实例化一个DataStream。”
问题所在： 大量行话却无定义、无链接、无新手入门指引。
修正方法： 定义术语，链接到前置要求，提供快速入门指南。

2. Perfect World Examples

2. 理想化示例

Bad:
javascript
const myFile = document.getElementById('file-input').files[0];
const response = await uploadFile('/api/upload', myFile);
console.log('File uploaded successfully!');
Why it fails: No error handling, ignores edge cases (no file selected, network failure, file too large).
Fix: Wrap in try-catch, check response status, handle undefined files.
糟糕示例：
javascript
const myFile = document.getElementById('file-input').files[0];
const response = await uploadFile('/api/upload', myFile);
console.log('File uploaded successfully!');
问题所在： 无错误处理，忽略边缘情况（未选择文件、网络故障、文件过大）。
修正方法： 用try-catch包裹，检查响应状态，处理未定义文件的情况。

3. Vague and Unhelpful

3. 模糊无用的内容

Bad:
  • getUser(userId)
    : "Gets a user by their ID."
  • class DataProcessor
    : "A class for processing data."
  • processData(data)
    : "Processes the data."
Why it fails: Tautological. Says nothing beyond the function name.
Fix: Describe behavior, parameters, return values, exceptions. "Fetches user record from database, returns null if user doesn't exist. Throws AuthError if API key lacks read permissions."
糟糕示例：
  • getUser(userId)
    : "Gets a user by their ID."
  • class DataProcessor
    : "A class for processing data."
  • processData(data)
    : "Processes the data."
问题所在： 同义反复。除了函数名之外没有提供任何有用信息。
修正方法： 描述行为、参数、返回值、异常。例如：“从数据库中获取用户记录，若用户不存在则返回null。若API密钥缺乏读取权限则抛出AuthError。”

Pro-Examples from Industry Leaders

行业领导者的优秀示例

Supabase (Clarity + Depth)

Supabase（清晰性+深度）

"Row Level Security (RLS) is a PostgreSQL feature that allows you to control which rows a user can access in a table. When you enable RLS on a table, all SELECT, INSERT, UPDATE, and DELETE operations are subject to a security policy. A policy is a SQL expression that returns a boolean value. If the expression returns true, the operation is allowed to proceed. If it returns false or null, the operation is denied."
Why it works: Defines RLS, explains scope (CRUD operations), defines mechanism (policy = SQL boolean expression). Dense with information, perfectly clear.
“Row Level Security (RLS)是PostgreSQL的一项功能，允许你控制用户可访问表中的哪些行。当你在表上启用RLS后，所有SELECT、INSERT、UPDATE和DELETE操作都需遵守安全策略。安全策略是一个返回布尔值的SQL表达式。若表达式返回true，则操作被允许；若返回false或null，则操作被拒绝。”
成功原因： 定义了RLS，说明了适用范围（CRUD操作），解释了实现机制（策略=SQL布尔表达式）。信息密度高，且非常清晰。

Stripe (Predictable Contract)

Stripe（可预测的约定）

"Stripe uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Stripe's servers."
Why it works: Establishes predictable contract for fundamental API behavior. Technical, precise, immediately useful.
“Stripe使用常规HTTP响应码来指示API请求的成功或失败。一般来说：2xx范围内的代码表示成功；4xx范围内的代码表示请求因提供的信息有误而失败；5xx范围内的代码表示Stripe服务器出现错误。”
成功原因： 为API的基础行为建立了可预测的约定。技术准确、表述精准，立即可用。

Astro (Anticipates Questions)

Astro（预判用户问题）

"You can run create-astro anywhere on your machine, so you don't have to create an empty directory for your project first. If you don't have an empty directory yet, the wizard will help you create one."
Why it works: Anticipates common beginner question ("Do I need to make a folder first?") and answers it proactively.
“你可以在机器上的任何位置运行create-astro，因此无需先为项目创建空目录。如果你还没有空目录，向导会帮你创建一个。”
成功原因： 预判了初学者的常见问题（“我需要先创建文件夹吗？”）并主动给出答案。

Tailwind CSS (Teaches Philosophy)

Tailwind CSS（传递设计理念）

"The biggest maintainability concern when using a utility-first approach is managing commonly repeated utility combinations. The traditional approach is to extract repeated utilities into a component class. We believe that @apply should be used sparingly. The best way to manage repeated utility combinations is to create reusable components with a templating language."
Why it works: Identifies problem, presents common solution, explains why that solution is suboptimal, guides toward better approach. Teaches philosophy, not just features.
“使用实用优先方法时，最大的可维护性问题是管理重复出现的工具类组合。传统方法是将重复的工具类提取到组件类中。我们认为应谨慎使用@apply。管理重复工具类组合的最佳方式是使用模板语言创建可复用组件。”
成功原因： 指出问题，给出常见解决方案，解释该方案为何不理想，引导用户采用更好的方法。传递的是理念，而非仅仅是功能。

Writing That Feels Human

让写作更具人情味

Use Contractions

使用缩写形式

AI defaults to:
  • "It is important that you do not..."
  • "You will need to..."
Human writing:
  • "It's important that you don't..."
  • "You'll need to..."
AI默认写法：
  • “It is important that you do not..."
  • "You will need to..."
人性化写法：
  • “It's important that you don't..."
  • "You'll need to..."

Vary Sentence Length

变换句子长度

AI writes: Every paragraph is 3-4 sentences. Every sentence is 15-20 words. Everything feels perfectly balanced and rhythmic in an uncanny way.
Human writes: Short sentences create emphasis. Longer sentences provide context, explanation, or explore nuance that requires more breathing room. Mix them. Create rhythm naturally.
AI的写法： 每个段落3-4句，每个句子15-20词。所有内容都显得完美平衡、节奏一致，给人一种诡异的感觉。
人性化写法： 短句用于强调，长句用于提供上下文、解释或探索需要更多空间的细微差别。混合使用，自然营造节奏。

Add Personality

加入个性

AI avoids:
  • First person ("I," "we")
  • Opinions
  • Personal anecdotes
  • Humor
Human includes:
  • "We tried the obvious solution first and it failed"
  • "I found this approach more practical because..."
  • Opinions grounded in experience
  • Self-aware observations
AI会避免：
  • 第一人称（“I,” “we”）
  • 观点
  • 个人轶事
  • 幽默
人性化写法会包含：
  • “我们先尝试了最明显的解决方案，但失败了”
  • “我发现这种方法更实用，因为...”
  • 基于经验的观点
  • 有自我认知的观察

Break Grammar Rules Intentionally

有意打破语法规则

AI never:
  • Starts sentences with "And" or "But"
  • Uses sentence fragments
  • Ends with prepositions
Human does:
  • "And that's exactly the point." (emphasis)
  • "This is what we're dealing with." (natural)
AI绝不会：
  • 以“And”或“But”开头
  • 使用句子片段
  • 以介词结尾
人性化写法会：
  • “And that's exactly the point.”（强调）
  • “This is what we're dealing with.”（自然）

Be Specific

具体化表述

AI writes vaguely:
  • "This approach offers significant benefits"
  • "Companies have seen improved results"
Human writes specifically:
  • "We reduced latency from 450ms to 120ms"
  • "Three team members raised concerns about X"
AI的模糊写法：
  • “This approach offers significant benefits”
  • “Companies have seen improved results”
人性化的具体写法：
  • “我们将延迟从450ms降低到了120ms”
  • “三位团队成员对X提出了担忧”

Code Comments and Documentation

代码注释与文档

Punctuation

标点符号

Always use periods at the end of code comments.
typescript
// Good: Validates user input before processing.
// Bad: validates user input before processing
代码注释结尾务必使用句号。
typescript
// Good: Validates user input before processing.
// Bad: validates user input before processing

Headings

标题

Use sentence case in all headings. Never title case.
markdown
Good: ## Error handling patterns
Bad:  ## Error Handling Patterns

Good: ### When to use async
Bad:  ### When To Use Async
所有标题使用句子式大小写，绝不使用标题式大小写。
markdown
Good: ## Error handling patterns
Bad:  ## Error Handling Patterns

Good: ### When to use async
Bad:  ### When To Use Async

Error Messages

错误信息

Format error messages as lowercase sentence fragments. They compose naturally when chained.
Good: failed to parse configuration: invalid JSON at line 42
Bad:  Failed to Parse Configuration: Invalid JSON at Line 42
The lowercase format works because errors often chain: 
"operation failed: " + innerError.message
reads correctly.
错误信息格式为小写的句子片段。这样在链式调用时会更自然。
Good: failed to parse configuration: invalid JSON at line 42
Bad:  Failed to Parse Configuration: Invalid JSON at Line 42
小写格式之所以有效，是因为错误经常会链式出现：
"operation failed: " + innerError.message
读起来很自然。

Red Flags - Review Checklist

警示信号 - 审核清单

Before publishing, check for these issues:
  • No AI phrases ("delve," "leverage," "robust," "at its core")
  • No throat-clearing openings ("Let me explain," "It's important to note")
  • No hedging language ("basically," "generally speaking")
  • No marketing fluff ("powerful," "revolutionary," "cutting-edge")
  • Sentence length varies (not all 15-20 words)
  • Paragraph length varies (not all 3-4 sentences)
  • Contractions used naturally ("it's" not "it is")
  • Active voice, clear actors (not "it can be seen that")
  • Code examples include error handling
  • WHY explained for design decisions
  • Technical terms defined on first use
  • Specific numbers/names/details (not vague claims)
  • Read aloud test - does it sound natural?
  • Code comments end with periods
  • Headings use sentence case (not Title Case)
  • Error messages are lowercase sentence fragments
发布前，请检查以下问题：
  • 无AI短语（如“delve,” “leverage,” “robust,” “at its core”）
  • 无铺垫性开头（如“Let me explain,” “It's important to note”）
  • 无模糊性措辞（如“basically,” “generally speaking”）
  • 无营销话术（如“powerful,” “revolutionary,” “cutting-edge”）
  • 句子长度多变（并非全部15-20词）
  • 段落长度多变（并非全部3-4句）
  • 自然使用缩写形式（如“it's”而非“it is”）
  • 使用主动语态，主体明确（避免“it can be seen that”这类表述）
  • 代码示例包含错误处理
  • 设计决策说明了原因
  • 技术术语首次出现时已定义
  • 使用具体数字/名称/细节（而非模糊表述）
  • 朗读测试——听起来是否自然？
  • 代码注释结尾使用句号
  • 标题使用句子式大小写（而非标题式大小写）
  • 错误信息为小写句子片段

Common Mistakes and Fixes

常见错误与修正方法

MistakeRealityFix
"Just being thorough with explanations"You're explaining obvious things.Delete explanations of what developers already know.
"Keeping it professional with formal language"Formal = robotic.Use contractions, conversational tone, natural language.
"Covering all the edge cases upfront"Overwhelms reader.Basic case first, advanced section for edge cases.
"Using precise technical terminology"Jargon without definitions loses readers.Define terms on first use, link to glossary.
"Being careful with hedging language"Hedging makes you sound uncertain.State facts directly. Remove qualifiers.
"Perfect code examples look cleaner"Perfect world examples are brittle in practice.Include error handling, show realistic usage.
"More examples = more helpful"Too many examples = noise.One excellent, complete example beats five shallow ones.
错误实际问题修正方法
“只是想把解释做得全面一些”你在解释开发者已经知道的内容删除对开发者已知内容的解释
“用正式语言保持专业性”正式=机械使用缩写形式、口语化语气、自然语言
“提前涵盖所有边缘情况”会让读者不知所措先讲基础场景，用高级部分讲解边缘情况
“使用精准的技术术语”无定义的行话会让读者困惑首次出现时定义术语，链接到术语表
“谨慎使用模糊性措辞”模糊表述会让你听起来不确定直接陈述事实，删除限定词
“完美的代码示例看起来更简洁”理想化示例在实际中很脆弱包含错误处理，展示真实使用场景
“示例越多越有帮助”过多示例会造成干扰一个优秀的完整示例胜过五个肤浅的示例

Summary

总结

Technical writing in three rules:
  1. Clear and concise - Short sentences, short paragraphs, active voice, no filler
  2. Authentic voice - Contractions, varied rhythm, personality, specific details
  3. Explain why - Design decisions, tradeoffs, non-obvious patterns need justification
Avoid AI markers: No "delve," "leverage," "robust." No throat-clearing. No hedging. No formal transitions.
One excellent example beats five mediocre ones. Include error handling. Show realistic usage.
Technical depth + clarity are not opposites. You can have both. Supabase, Stripe, and Cloudflare prove this daily.
Read aloud test: If it sounds robotic or overly formal, rewrite it.
技术写作三规则：
  1. 清晰简洁 - 短句、短段落、主动语态、无冗余内容
  2. 真实语气 - 使用缩写、多变节奏、加入个性、具体细节
  3. 解释原因 - 设计决策、权衡、非显而易见的模式需要说明理由
避免AI痕迹： 不使用“delve,” “leverage,” “robust”这类词汇。无铺垫性语句。无模糊性措辞。无正式过渡词。
一个优秀的示例胜过五个平庸的示例。包含错误处理，展示真实使用场景。
技术深度与清晰性并非对立关系。 二者可以兼得。Supabase、Stripe和Cloudflare每天都在证明这一点。
朗读测试： 如果听起来机械或过于正式，请重写。