从零到专业级的技术写作方法论
目录导读
为什么开源文档需要“英文优先”？
在GitHub、GitLab等平台上，超过70%的开源项目采用英文作为主要文档语言，这并非“崇洋媚外”,而是因为：
- 国际化协作：英文是开源社区的事实标准,能吸引全球贡献者。
- 搜索引擎覆盖：英文技术查询在Stack Overflow、Google上占比最高,英文文档能获得更多自然流量。
- 工具链兼容性：如Read the Docs、Sphinx、Docusaurus等主流文档工具,默认对英文支持最完善。
但注意：你的目标读者不一定是母语者。清晰、简洁、可扫描比华丽辞藻更重要。
开源英文文档的核心写作原则
KISS原则（Keep It Simple, Stupid）
- 用短句：每个句子不超过20个单词。
- 避免连词成瘾：少用“which”、“that”、“although”引导的从句。
- 案例对比：
❌ “The function, which when called with incorrect parameters, will likely throw an exception that you should handle appropriately.”
✅ “Call the function with valid parameters. Otherwise, it throws an exception.”
主动语态 + 现在时
- 主动语态更直接：“You can install the package using npm.” 而非 “The package can be installed...”
- 现在时描述持续行为：“The CLI outputs JSON” 而非 “will output”。
一致性优先
- 术语统一：别一会儿用“parameter”，一会儿用“argument”，大小写**：建议用“Sentence case”（仅首字母大写，如“How to install”）而非“Title Case”（每个词大写，如“How To Install”），前者在搜索引擎结果页（SERP）中更易读。
结构可扫描性
- 用户不会逐字阅读，而是扫视。
- 、列表、代码块。
- 关键步骤用加粗或序号列出。
- 代码示例必须带语法高亮。
七步打造高质量英文文档的实战流程
第一步：确定文档类型
开源文档通常分三类，每类侧重点不同： | 文档类型 | 目标 | 示例 | |---------|------|------| | 入门指南 | 让用户5分钟内跑通一个例子 | “Getting Started with React” | API参考 | 精确描述函数/参数/返回值 | “TitleInputProps” | | 教程/概念解释 | 解释为什么这样设计 | “Understanding State Management” |
第二步：建立术语表（Glossary）
- 创建
glossary.md，列出所有专有名词、缩写及中文对照。 - API（Application Programming Interface）、CLI（Command-Line Interface）。
第三步：按“倒金字塔”书写内容
每节开头放最重要的信息，再展开细节,参考格式：
- 一句话总结：This command installs all dependencies.”
- 代码示例（必须可复制运行）
- 参数说明（表格形式）
- 常见错误提示（FAQ形式）
第四步：使用“问题驱动”的标题是搜索的入口。
- 不对：“Configuration Section”
- 对：“How to Customize the Theme Colors”
第五步：写“防出错”的代码示例
- 总是展示完整代码，而非片段，提供完整的
import语句。 - 标注预期输出：用注释
# Output: Hello World。 - 版本标注：如果API在不同版本有差异，用
⚠️ Version >= 2.0提醒。
第六步：加入本地化信号
虽然文档用英文,但你可以：
- 在README中提供文档翻译的贡献指引（“We welcome translations! Create a PR for your language.”）
- 对复杂概念提供视觉辅助：例如用ASCII图表或Mermaid流程图。
第七步：做一次“英文母语者”的review
即使你英语流利，最好请一位英语母语者或资深技术写手审阅,重点关注：
- 冠词（a/an/the）是否滥用或缺漏。
- 介词搭配（如“depend on”而非“depend of”）。
常见陷阱与避坑指南
❌ 陷阱1: 过度使用“Please”和“Thank you”
技术文档应保持中性，避免“Please enter your name”，直接说“Enter your name.”
❌ 陷阱2: 忽略标点符号的国际化
- 美式英语句点后空格：一个单词后接一个空格（如“Click here. Then wait.”）。
- 冒号后接空格：
Note: the function returns null.
❌ 陷阱3: 用词模糊
- 坏：“You might want to check the log.”
- 好：“To debug, check the log at
/var/log/error.log.”
❌ 陷阱4: 忽略用户的“时间成本”
- 在文档开头添加 TL;DR（Too long; didn’t read）段落,让用户30秒内了解核心。
- “TL;DR: Run
npm installand thennpm startto see the demo.”
QA：你的文档撰写疑问全解答
Q1：写英文文档时，可以用“you”称呼用户吗？
A：可以，并且推荐，使用“you”比“user”更直接，也能避免性别代词。“You can configure the timeout.”
Q2：如何平衡详细度和简洁性？
A：把详细信息放在代码注释或扩展阅读中，正文只写“如何做”，注释写“为什么这么做”。 “Run npm run build.”
注释：“This command uses Webpack with production mode. Change webpack.config.js to adjust.”
Q3：我的开源项目小众，也要写英文文档吗？
A：至少写一个简明英文README，即便用户用中文搜索，他们也可能通过GitHub等平台发现你的项目——英文README能降低参与门槛,吸引海外贡献者。
Q4：应该用工具的自动翻译功能吗？
A：不推荐直接使用机器翻译，但可以使用DeepL或Grammarly辅助润色语法，再人工校准术语和语气，在README中注明“translated with AI-assisted tools”会更诚实。
Q5：文档被用户提issue说看不懂怎么办？
A：这是改进的机会，根据issue提示，增加以下内容：
- 更详细的安装步骤（包括失败时怎么办）。
- 一个完整的、从零开始的示例项目（可放在“examples”文件夹）。
- 在文档中加入“Troubleshooting”部分。
但不是最后一行）
写开源英文文档，本质上是在用文字建造一座桥梁，连接你的代码与全球开发者，不必追求完美无瑕的语法，但要追求每一步都可执行、每一句都清晰，你可以从一个简单的README开始，加入GitHub Actions自动检查拼写（如spell-checker），然后持续迭代，好文档不是写出来的，是改出来的——而每一次修改,都让开源社区的协作更顺畅一分。
