第七章技术写作：文档与博客 — 程序员英语实战手册

7.1 技术写作的核心审美

技术写作不是文学写作。它的目标只有一个：让读者尽快做对事。所以好的技术英文有四个特征：

具体（concrete）。"快"不行，要 "p99 latency < 200ms"；"很多"不行，要 "10k requests/sec"。
主动（active voice）。"the cache is updated by the worker" → "the worker updates the cache"。
简短（brief）。一句不超过 25 词。
可扫读（scannable）。用标题、列表、加粗词、代码块切分内容，让读者跳着读也不会漏关键点。

对比：

# Bad — 长、被动、抽象
The performance optimization that has been implemented in this version
of the library leverages various caching mechanisms in order to ensure
that requests can be handled in a more efficient manner under conditions
of high load.

# Good — 短、主动、具体
v2.4 introduces an in-memory LRU cache (1000 entries, 60s TTL) on the
hot path. Under 5k req/s sustained load, p99 latency drops from
180ms to 22ms.

7.2 README 的标准结构

一个完整的开源项目 README 通常包含以下板块。GitHub 上 1k+ stars 的项目几乎都遵循这个顺序：

# Project Name

<一行描述：what + for whom>

[![CI](badge-url)](link) [![npm](badge-url)](link) [![license](badge-url)](link)

## Why <Project Name>?
（动机：解决了什么问题？比已有方案好在哪？）

## Quick Start
```bash
npm install xxx
```
```js
import xxx from 'xxx'
xxx.do()
```

## Features
- ✨ X
- 🚀 Y
- 🔒 Z

## Documentation
Full documentation at https://...

## Examples
- [Example 1](./examples/01-basic)
- [Example 2](./examples/02-advanced)

## Configuration
<表格列出所有 options>

## API Reference
<链接到完整 API doc 或简版 inline>

## Comparison
| Feature | Us | Competitor A | Competitor B |
|---------|----|----|----|

## Performance
<benchmark 数据>

## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md)

## Roadmap
- [x] v1.0 launched
- [ ] v1.1: feature X (Q2 2024)
- [ ] v2.0: rewrite in Y

## License

MIT © Author Name

## Acknowledgments
Inspired by <X>. Thanks to <Y> for the original idea.

README 第一句的写法

第一句必须在 15 词内说清楚 "这是什么 + 给谁用"。这是项目第一印象，也是 GitHub search 算法主要看的字段。

# 优秀第一句的公式：
<Project> is a <type> for <audience> that <differentiator>.

# 真实例子
"Bun is an all-in-one JavaScript runtime & toolkit designed for speed."

"Tailwind CSS is a utility-first CSS framework for rapidly building
custom designs."

"Drizzle is a TypeScript ORM for SQL databases that feels like writing
SQL but with full type safety."

"FastAPI is a modern, fast web framework for building APIs with Python
based on standard Python type hints."

README 反模式

# Bad — 没有功能描述，只是历史叙述
Welcome to my project! I started this in 2022 because I needed
something for my own use, and over time it grew into ...

# Bad — 充满营销语
The most powerful, intuitive, blazing-fast solution for all your needs!

# Bad — 上来就是 install
## Installation
npm install foo

# 读者还没决定要不要装，就让他装

7.3 API 文档写作

API 文档的核心结构（每个 endpoint 必备）：

### POST /v1/charges

Creates a new charge against a customer's payment method.

#### Request

| Parameter   | Type    | Required | Description                          |
|-------------|---------|----------|--------------------------------------|
| amount      | integer | Yes      | Amount in smallest currency unit     |
| currency    | string  | Yes      | ISO 4217 lowercase code              |
| customer    | string  | No       | Customer ID                          |
| description | string  | No       | Free-form description                |

#### Response

```json
{
  "id": "ch_abc123",
  "status": "succeeded",
  "amount": 1000,
  "currency": "usd",
  "created": 1707000000
}
```

#### Errors

| Status | Code              | Meaning                            |
|--------|-------------------|-----------------------------------|
| 400    | invalid_request   | Missing required parameter         |
| 402    | card_declined     | Card was declined by the issuer    |
| 402    | insufficient_funds| Card has insufficient funds        |
| 429    | rate_limited      | Too many requests                  |

#### Example

```bash
curl https://api.example.com/v1/charges \
  -u sk_test_abc123: \
  -d amount=1000 \
  -d currency=usd
```

#### Idempotency

This endpoint is idempotent when an `Idempotency-Key` header is
provided. Repeated requests with the same key return the original
response.

#### Rate limit

100 requests per second per API key. Exceeded requests return 429
with a `Retry-After` header.

API doc 描述参数的句式

# 类型 + 必填性 + 含义 + 例子（如非显然）
"A positive integer representing the amount in cents (e.g., 100 for $1.00)."

# 默认值放在最后
"The cache TTL in seconds. Defaults to 60."

# 可选值用 enum
"The sort order. One of: 'asc', 'desc'. Defaults to 'desc'."

# 互斥参数
"You must provide either `customer` or `source`, but not both."

# 范围限制
"An integer between 1 and 100, inclusive."

# 长度限制
"A string up to 500 characters."

7.4 技术博客的开篇技巧

技术博客最怕开头三段还在 "introducing concept X"。读者来博客是因为有具体问题要解决——开头三句必须命中 hook。

四种经典开篇

开篇 1：Hook + Problem

We rolled out a feature flag last Tuesday. By Wednesday morning,
our login latency had tripled.

This is the story of how a 200-line refactor accidentally killed
our database, and what we learned in the 48 hours it took to
recover.

开篇 2：Surprising Statement

You probably don't need a state management library.

I know that sounds heretical in 2024, but hear me out. After
shipping three React apps without Redux/Zustand/Jotai, here's
what changed my mind.

开篇 3：Question

Why is `npm install` so slow?

It's a question every JavaScript developer has asked. The answer
turns out to be more interesting — and more fixable — than I
expected.

开篇 4：Concrete Number

We reduced our Docker image size from 1.2 GB to 47 MB by changing
five lines.

Here's exactly what we changed and why each line mattered.

共同点：第一段就给读者具体收获或具体故事，不浪费在 "today I want to talk about X"。

7.5 Tutorial 文章的步骤化语言

Tutorial 的英语有一套高度仪式化的句型，新手按模板写就比 90% 的中文翻译版自然：

引导动作

"First, install the dependencies:"
"Next, create a new file called `app.ts`:"
"Then, run the following command:"
"After that, open your browser to localhost:3000."
"Finally, deploy with `vercel --prod`."

# 反例（中式）
"At first, you should install the dependencies"   # at first 用法不当
"Then you can to create a new file"               # to 多余

解释代码

"In the snippet above, we ..."
"Notice how X passes Y as a prop to Z."
"This works because ..."
"You'll see that ..."
"The key part here is ..."

# 反例
"In the above snippet, we are ..."           # we are 不如 we 简洁
"Please notice that ..."                      # please 多余且生硬

引导测试

"Try it out by clicking the button."
"Refresh the page and you should see ..."
"To verify, run `npm test`. All tests should pass."
"If everything went well, you'll see <screenshot>."

故障排查

"If you get an error like X, it usually means ..."
"Make sure to ..."
"Common pitfalls:"
"If the build fails with `EACCES`, try running with sudo."

过渡到下一节

"Now that we have X working, let's add Y."
"With the basic setup done, we can move on to ..."
"That covers the happy path. In the next section, we'll handle errors."

7.6 避免 AI 味道

2023 年后，"AI 味道"（AI smell）成了技术写作里最大的反模式。读者看一眼就能识别——这种文风让人本能怀疑作者根本没写过、只是 ChatGPT 输出。

AI 味道的 6 个特征

过度连接词：Furthermore, Moreover, In addition, However, Therefore — 一篇文章用了十几个。
三明治结构：每段都是 "总-分-总"，每节都有 "In summary"。
陈词滥调："In today's fast-paced world", "delve into", "unlock the power of", "navigate the complexities", "harness", "robust"。
正负平衡：每讨论一个优点必须配缺点，每讨论一个缺点必须配优点。真实写作不会这么对称。
列表优先：什么都列成 bullet list，连 1-2 项都列。
"It's important to note that"：这条出现的频率几乎可以当 LLM 检测器。

对比

# AI 味道
In today's rapidly evolving software landscape, it's important to note
that microservices architecture has emerged as a powerful paradigm
that offers numerous benefits. However, it's equally important to
recognize that microservices come with their own set of challenges.
Furthermore, organizations must carefully navigate the complexities
of distributed systems to harness the full potential of this approach.

# 人写的
Microservices solve one problem (deploy independently) and create
five (network calls, distributed tracing, schema versioning, ops
overhead, debugging across services). At <scale X> the trade is worth
it. Below that, you're paying overhead for benefits you can't yet use.

避免 AI 味道的 5 个习惯

用具体数字代替形容词。"很大" → "1.2 GB"，"很慢" → "p99 = 180ms"。
用具体例子代替抽象。"用户体验差" → "用户点 Submit 后等了 3 秒才看到反馈"。
不平衡描述。如果你的观点是"A 比 B 好"，不要为了平衡硬加一段 B 的优点。
句长 / 句式变化。AI 倾向于平均 18-22 词的中等长度句。人类应当短长穿插，偶尔甚至来一个独立单词的短句作为节奏。Like this.
有主见。"我推荐 X" 比 "X 是一种值得考虑的选择" 强一万倍。

// trap

用 AI 起草是 OK 的，但必须自己改一遍——把套话删掉、把抽象换具体、加你自己的观点。直接把 AI 输出贴出去的博客，技术圈一眼识破。

7.7 100 个高频技术写作动词

程序员英语的"声音"很大程度由动词决定。下面是 100 个高频动词，按场景分组——把它们替换掉你常用的 do/use/make/get，文风立刻提升一档。

实现与构建（20 个）

implement, build, ship, introduce, add, expose, provide,
establish, set up, wire up, hook up, integrate, embed, register,
extend, layer on, lift up, scaffold, bootstrap, instantiate

处理与转换（20 个）

process, handle, transform, normalize, parse, serialize, decode,
encode, convert, map, reduce, aggregate, flatten, sanitize, validate,
filter, dispatch, route, propagate, forward

优化与重构（15 个）

optimize, refactor, simplify, streamline, consolidate, deduplicate,
decouple, extract, inline, hoist, lazy-load, memoize, batch, debounce,
throttle

抽象与建模（15 个）

abstract, encapsulate, generalize, specialize, leverage, derive,
compose, wrap, decorate, proxy, delegate, mock, stub, fake, shim

错误与状态（15 个）

throw, raise, catch, recover, retry, fall back, propagate, surface,
short-circuit, bail, abort, cancel, timeout, debounce, gate

性能与扩展（15 个）

scale, parallelize, pipeline, fan out, fan in, shard, partition,
replicate, cache, prefetch, warm up, cool down, throttle, backpressure,
saturate

实例对比（同一句话用不同动词）：

# 平淡
We use a function to make user info from raw data.

# 升级 1
We transform raw user data into a normalized profile.

# 升级 2
The pipeline parses raw events, normalizes user attributes, and
emits typed `UserProfile` records downstream.

7.8 常见英语写作错误

错误 1：too long sentences

中国程序员最常见的问题。中文一个长句的密度可以很高，英语硬翻译就变成 50 词的怪物。

# Bad
The system that we have built which uses Redis as a backing store
in order to provide caching capabilities for the user authentication
service that handles login requests has been performing well.

# Good — 拆成 3 句
We back the user-auth cache with Redis. It serves all login
requests. So far it's holding up well.

错误 2：被动语态滥用

# Bad
The cache is invalidated by the worker when the user is updated.
A 5xx response is returned by the server when ...

# Good
The worker invalidates the cache on user update.
The server returns 5xx when ...

错误 3：dangling modifier

# Bad — Walking 修饰的是 the cache 还是 someone？
Walking through the code, the cache implementation seems wrong.

# Good
Walking through the code, I noticed the cache implementation seems wrong.
On a closer look, the cache implementation seems wrong.

错误 4：article 错（a/an/the）

# Bad
The function returns user with given id.

# Good
The function returns the user with the given ID.
The function returns a user matching the given ID.

错误 5：可数 / 不可数错配

# Bad
We need more informations.    # information 不可数
He gave me an useful advice.   # advice 不可数
The softwares are open source. # software 不可数

# Good
We need more information.
He gave me useful advice.
The software is open source.   # 或 these tools / packages

7.9 写作工具与流程

用 Markdown 写，不要 Word。技术写作的格式天生适合 Markdown。
装 Grammarly / LanguageTool。免费版就够用。
用 Hemingway Editor 检查可读性。控制在 Grade 8-10。
朗读你写的英文。读不顺的地方一定要改——母语读者也读不顺。
给你信任的同事看一遍。别人 5 分钟看出的问题，你自己 2 小时也看不出。
发出去后 24 小时再看一遍。冷却期暴露的问题最多。

7.10 本章小结

技术写作四特征：具体、主动、简短、可扫读。
README 标准结构：first sentence + Why + Quick Start + Features + Examples + Comparison。
API doc 必备：参数表 + 返回 + 错误 + 示例 + 幂等性 + 速率限制。
博客四种开篇：Hook+Problem / Surprising / Question / Concrete Number。
Tutorial 步骤化：First / Next / Then / Finally + Notice / Try it out。
避免 AI 味道：删套话、用数字、不平衡、句式变化、有主见。
100 高频动词替换平淡 do/use/make/get。
常见错：长句、被动滥用、dangling modifier、article、可数。

下一章我们换到口语场景——远程会议英语。