优秀文档的核心原则 —— 来自 OpenAI 团队 Cookbook
文档的核心目标是将有用信息高效注入读者的头脑中，避免读者在信息海洋中迷失。优秀文档不是长篇大论，而是通过结构化、清晰和共情的设计，帮助读者快速解决问题。
1. 让文档易于浏览（Make docs easy to skim）
读者很少从头到尾线性阅读文档，他们更倾向于跳跃式浏览，寻找直接解决问题的部分。因此，文档应像一张高效的“信息地图”，降低搜索成本，提高成功率。
· 使用描述性标题：标题应是信息完整的句子，而非抽象名词。例如，用“流式处理将首 token 响应时间缩短50%”代替“结果”，让读者无需深入阅读即可获知要点。
· 添加目录：目录如哈希表般加速定位，同时提供文档整体线索，帮助读者判断是否值得阅读。
· 保持段落简短：短段落易于扫描；关键点可独立成一句单句段落，避免被长文淹没。
· 以独立主题句开头：段落和节的首句应自成一体，不依赖前文。例如，“向量数据库可加速嵌入搜索”优于“基于此，让我们讨论更快的方法”，便于跳读者快速理解。
· 主题词置于句首：如“向量数据库加速嵌入搜索”比“嵌入搜索可由向量数据库加速”更高效，因为读者只需读前两词即可把握主题。
· 要点前置：将最重要的信息置于文档或节的顶部，避免司马式渐进式展开，先结果后过程。
· 多用 bullet 列表和表格：这些格式天然支持扫描，提高可读性。
· 加粗关键文本：大胆突出重要内容，帮助读者快速锁定。
这些技巧的核心是“读者优先”：设计时假设读者时间有限、注意力分散。
2. 写出高质量文本（Write well）
糟糕的文风会消耗读者的认知资源，导致疲劳。优秀文档应追求简洁、流畅，减少解析负担。
· 句子简洁：拆分长句、去除副词和冗余词，使用祈使语气（如写作书籍建议）。
· 确保无歧义解析：避免词性模糊的句子。例如，“用句子标题节”（Title sections with sentences）易混淆词性；改为“将节标题写成句子”（Write section titles as sentences）更易解析，即使稍长。
· 避免左分支句子：这类句子要求读者短期记忆过多，如“你需要面粉、鸡蛋、牛奶、黄油和少许盐来做煎饼”。改为右分支：“做煎饼需要面粉、鸡蛋、牛奶、黄油和少许盐”，更符合大脑处理习惯（类似于深度优先搜索）。
· 少用指示代词：如“this”跨句使用易造成回溯负担。改
文档的核心目标是将有用信息高效注入读者的头脑中，避免读者在信息海洋中迷失。优秀文档不是长篇大论，而是通过结构化、清晰和共情的设计，帮助读者快速解决问题。
1. 让文档易于浏览（Make docs easy to skim）
读者很少从头到尾线性阅读文档，他们更倾向于跳跃式浏览，寻找直接解决问题的部分。因此，文档应像一张高效的“信息地图”，降低搜索成本，提高成功率。
· 使用描述性标题：标题应是信息完整的句子，而非抽象名词。例如，用“流式处理将首 token 响应时间缩短50%”代替“结果”，让读者无需深入阅读即可获知要点。
· 添加目录：目录如哈希表般加速定位，同时提供文档整体线索，帮助读者判断是否值得阅读。
· 保持段落简短：短段落易于扫描；关键点可独立成一句单句段落，避免被长文淹没。
· 以独立主题句开头：段落和节的首句应自成一体，不依赖前文。例如，“向量数据库可加速嵌入搜索”优于“基于此，让我们讨论更快的方法”，便于跳读者快速理解。
· 主题词置于句首：如“向量数据库加速嵌入搜索”比“嵌入搜索可由向量数据库加速”更高效，因为读者只需读前两词即可把握主题。
· 要点前置：将最重要的信息置于文档或节的顶部，避免司马式渐进式展开，先结果后过程。
· 多用 bullet 列表和表格：这些格式天然支持扫描，提高可读性。
· 加粗关键文本：大胆突出重要内容，帮助读者快速锁定。
这些技巧的核心是“读者优先”：设计时假设读者时间有限、注意力分散。
2. 写出高质量文本（Write well）
糟糕的文风会消耗读者的认知资源，导致疲劳。优秀文档应追求简洁、流畅，减少解析负担。
· 句子简洁：拆分长句、去除副词和冗余词，使用祈使语气（如写作书籍建议）。
· 确保无歧义解析：避免词性模糊的句子。例如，“用句子标题节”（Title sections with sentences）易混淆词性；改为“将节标题写成句子”（Write section titles as sentences）更易解析，即使稍长。
· 避免左分支句子：这类句子要求读者短期记忆过多，如“你需要面粉、鸡蛋、牛奶、黄油和少许盐来做煎饼”。改为右分支：“做煎饼需要面粉、鸡蛋、牛奶、黄油和少许盐”，更符合大脑处理习惯（类似于深度优先搜索）。
· 少用指示代词：如“this”跨句使用易造成回溯负担。改