openai-cookbook：what makes documentation good（翻译总结）

RQfreefly · 2025-10-24 21:09:41 发布

分段与标题
把内容分成有标题的部分。标题就像路标，告诉读者该专注于哪里，或者是否该跳过。
信息型标题优于抽象名词
优先使用“信息型标题”而非“抽象名词”标题。
例如：
- 不佳示例：“结果”
- 更好示例：“流式处理将首个 token 时间减少了 50%”
添加目录
目录能让读者更快找到信息，就像哈希表查找比链表快。
同时，目录能让读者对文档内容形成预期，从而判断是否值得阅读全文。
段落要短
短段落更容易浏览。重要内容可独立成段，用一句话突出。长段落会掩埋重点。
开头句要有主题感
每个段落或章节开头写简短的主题句，让它能独立概述内容。
示例：
- 不佳：“基于以上，我们来谈谈更快的方法。”
- 更好：“向量数据库可以加速嵌入搜索。”
主题词置于句首
把主题词放在句子最前面，让读者快速判断段落内容。
示例：
- 不佳：“嵌入搜索可以通过向量数据库加速。”
- 更好：“向量数据库加速嵌入搜索。”
结论先行
把最重要的信息放在文档和每节的开头。不要先讲过程再讲结果。
善用列表与表格
项目符号与表格能显著提高可浏览性，要常用。
加粗重点
不要害怕使用粗体，帮助读者快速定位关键信息。

保持句子简洁
长句拆开；删副词；删掉冗余词；能用祈使句就用祈使句。
句子应易于解析
避免歧义结构。
示例：
- 不佳：“Title sections with sentences.”
- 更好：“Write section titles as sentences.”
避免左分支句
左分支句让读者在理解主句前得记住更多信息。
示例：
- 不佳：“You need flour, eggs, milk, butter and a dash of salt to make pancakes.”
- 更好：“To make pancakes, you need flour, eggs, milk, butter, and a dash of salt.”
避免模糊指代（如 this、that）
不要依赖读者回忆上文。
示例：
- 不佳：“Building on our discussion of the previous topic…”
- 更好：“Building on message formatting…”
保持一致性
格式统一，风格一致。不要让读者冒出“咦，这不对劲”的念头。
例如：标题格式、标点用法、命名方式都要保持一致。
不要假设读者心态
避免写“你现在可能想知道……”这类句子。
改写为中性表达：“要调用函数，……”

写得简单
比你认为必要的还要简单。考虑非英语母语读者或技术新手。
避免缩写
完整拼写术语。
示例：
- IF → instruction following
- RAG → retrieval-augmented generation（或更明晰的 “search-ask procedure”）
提供潜在问题的解决方案
即使 95% 的人会安装包或设置变量，也值得说明。对专家无碍，对新手帮助巨大。
用具体准确的术语
减少行话。
示例：
- “输入” 比 “提示词” 更清晰
- “最大 token 限制” 比 “上下文限制” 更直观
保持代码示例通用且可复用
减少依赖、避免额外安装、示例自洽。
按价值优先排序
常见问题（如计数 token）远比罕见问题（如优化 emoji 数据库）更有价值。
不传递坏习惯
如果 API key 不该出现在代码中，示例里也不要出现。
用宏观引入开场
介绍具体技术前，先讲通用背景。
例如在讲推荐系统时，先提 YouTube、Amazon、Wikipedia 等应用场景。