优秀文档的核心原则 —— 来自 OpenAI 团队 Cookbook

写文档是一种同理心的体现

文档的核心目标是将有用信息高效注入读者的头脑中，避免读者在信息海洋中迷失。优秀文档不是长篇大论，而是通过结构化、清晰和共情的设计，帮助读者快速解决问题。

让文档易于浏览

读者很少从头到尾线性阅读文档，他们更倾向于跳跃式浏览，寻找直接解决问题的部分。因此，文档应像一张高效的 “信息地图”，降低搜索成本，提高成功率。

●使用描述性标题：标题应是信息完整的句子，而非抽象名词。例如，用 “流式处理将首 token 响应时间缩短 50%” 代替 “结果”，让读者无需深入阅读即可获知要点。

●添加目录：目录如哈希表般加速定位，同时提供文档整体线索，帮助读者判断是否值得阅读。

●保持段落简短：短段落易于扫描；关键点可独立成一句单句段落，避免被长文淹没。

●以独立主题句开头：段落和节的首句应自成一体，不依赖前文。例如，“向量数据库可加速嵌入搜索” 优于 “基于此，让我们讨论更快的方法”，便于跳读者快速理解。

●主题词置于句首：如 “向量数据库加速嵌入搜索” 比 “嵌入搜索可由向量数据库加速” 更高效，因为读者只需读前两词即可把握主题。

●要点前置：将最重要的信息置于文档或节的顶部，避免司马式渐进式展开，先结果后过程。

●多用 bullet 列表和表格：这些格式天然支持扫描，提高可读性。

●加粗关键文本：大胆突出重要内容，帮助读者快速锁定。

这些技巧的核心是“读者优先”：设计时假设读者时间有限、注意力分散。

糟糕的文风会消耗读者的认知资源，导致疲劳。优秀文档应追求简洁、流畅，减少解析负担。

●句子简洁：拆分长句、去除副词和冗余词，使用祈使语气（如写作书籍建议）。

●确保无歧义解析：避免词性模糊的句子。例如，“用句子标题节”（Title sections with sentences）易混淆词性；改为 “将节标题写成句子”（Write section titles as sentences）更易解析，即使稍长。

●避免左分支句子：这类句子要求读者短期记忆过多，如 “你需要面粉、鸡蛋、牛奶、黄油和少许盐来做煎饼”。改为右分支：“做煎饼需要面粉、鸡蛋、牛奶、黄油和少许盐”，更符合大脑处理习惯（类似于深度优先搜索）。

●少用指示代词：如 “this” 跨句使用易造成回溯负担。改为具体名词：“基于消息格式，让我们讨论函数调用” 优于 “基于此讨论”。

●保持一致性：统一标题大小写、标点（如尾随逗号）和命名规范（如 Cookbook 中的下划线 + 句首小写），避免读者分心。

●不假设读者心态：避免 “你现在可能想了解函数调用” 这类推测；改为 “To call a function, …”，保持中立。

写作原则源于认知科学：减少大脑负载，让内容自然流动。

文档用户背景多样（从新手到专家、多语言使用者），优秀文档应包容性强，覆盖潜在痛点，而非仅针对 “理想读者”。

●用简单语言：比预期更简化解释（但不低估）。考虑非母语者和术语生疏者，优先清晰而非炫技。

●避免缩写：全写出，如 “instruction following” 而非 “IF”；“retrieval-augmented generation”（或 “搜索 - 询问流程”）而非 “RAG”。专家成本低，新手收益高。

●预解常见问题：即使 95% 读者知晓 Python 包安装，也值得说明 —— 专家可略过，新手避免卡壳。记住，跨语言专家（如 JavaScript 开发者）可能 Python 是新手。

●选用具体准确术语：避开行话，如用 “input” 代替 “prompt”，“max token limit” 代替 “context limit”，更自明且贴合实际。

●代码示例通用自洽：最小化依赖，避免额外库或跨页引用，确保可直接复制运行。

●优先高价值主题：聚焦常见问题（如 token 计数），而非罕见场景（如表情符号数据库优化）。

●避免不良习惯：如 API 密钥勿硬编码示例。

●以广义开场引入主题：如解释推荐系统时，先提及 YouTube、Amazon 等应用场景，增强读者安全感。

这些建议体现共情：文档是为 “所有人” 服务的工具，过多假设会疏离部分用户。

这些是指导而非铁律。文档写作是移情练习：代入读者视角，选择最有帮助的方式。最终，灵活应用才能适应具体情境。