文档将有用的信息放入他人的大脑中。遵循这些技巧来编写更好的文档。
使文档易于浏览
很少有读者从上到下线性阅读。他们会跳来跳去，试图评估哪一部分（如果有的话）能解决他们的问题。为了减少他们的搜索时间并增加成功的几率，使文档易于浏览。
将内容分成带标题的章节。 章节标题就像路标，告诉读者是应该集中注意力还是继续前进。
比起抽象名词，更喜欢使用信息丰富的句子作为标题。 例如，如果你使用像“结果”这样的标题，读者将需要深入阅读以下文本才能了解结果实际上是什么。相反，如果你使用标题“流式传输将首个令牌的时间减少了 50%”，它会立即给读者信息，而不会增加额外的负担。
包含目录。 目录帮助读者更快地找到信息，类似于哈希表比链表具有更快的查找速度。目录还有第二个经常被忽视的好处：它们为读者提供有关文档的线索，这有助于他们了解文档是否值得阅读。
保持段落简短。 较短的段落更容易浏览。如果你有一个要点，请考虑将其放在单独的一句话段落中，以减少被遗漏的可能性。长段落可能会埋没信息。
以简短的主题句开始段落和章节，提供独立的预览。 当人们浏览时，他们会不成比例地关注章节的第一个词、第一行和第一句话。编写这些句子时，使其不依赖于之前的文本。例如，考虑第一句话“在此基础上，现在让我们讨论一种更快的方法。” 对于没有阅读前一段的人来说，这句话毫无意义。相反，以一种可以独立理解的方式编写它：例如，“向量数据库可以加速嵌入搜索。”
将主题词放在主题句的开头。 当读者只需要阅读一两个词就能知道段落的内容时，他们浏览的效率最高。因此，在编写主题句时，最好将主题放在句子的开头而不是结尾。例如，假设你正在一篇关于嵌入搜索的长篇文章的中间写一段关于向量数据库的段落。与其写“嵌入搜索可以通过向量数据库加速”，不如写“向量数据库加速嵌入搜索”。第二句话更适合浏览，因为它将段落主题放在段落的开头。
将要点放在前面。 将最重要的信息放在文档和章节的顶部。不要写苏格拉底式的大构建。不要在结果之前介绍你的程序。
使用项目符号和表格。 项目符号列表和表格使文档更易于浏览。 经常使用它们。
粗体显示重要文本。 不要害怕粗体显示重要文本以帮助读者找到它。
写好
写得不好的文本阅读起来很费力。通过写好文章来最大限度地减少读者的负担。
保持句子简单。 将长句子分成两个。 删减副词。 删减不必要的词和短语。 如果适用，使用祈使语气。 按照写作书籍告诉你的去做。
编写可以明确解析的句子。 例如，考虑句子“用句子作为章节标题”。当读者读到“标题”这个词时，他们的大脑还不知道“标题”将是名词、动词还是形容词。当他们解析句子的其余部分时，需要花费一些脑力来跟踪，如果他们的大脑错误地预测了含义，可能会导致卡顿。 即使句子更长，也更喜欢更容易解析的句子（例如，“将章节标题写成句子”）。 同样，避免像“自行车间隙运动通知”这样的名词短语，这些短语可能需要额外的精力来解析。
避免左分支句子。 语言树显示了句子中单词之间的关系。 左分支树比右分支句子需要读者在内存中保留更多内容，类似于广度优先搜索与深度优先搜索。 左分支句子的一个例子是“你需要面粉、鸡蛋、牛奶、黄油和少许盐来制作煎饼。” 在这句话中，你直到句末才知道“你需要”连接到什么。 更容易阅读的右分支版本是“要制作煎饼，你需要面粉、鸡蛋、牛奶、黄油和少许盐。” 注意读者必须暂时记住的单词的句子，看看是否可以改写它们。
避免指示代词（例如，“这”），尤其是在句子之间。 例如，与其说“在讨论了前一个主题的基础上，现在让我们讨论函数调用”，不如尝试“在消息格式化的基础上，现在让我们讨论函数调用”。 第二句话更容易理解，因为它不会让读者回忆起前一个主题。 寻找完全删除指示代词的机会：例如，“现在让我们讨论函数调用。”
保持一致性。 人脑是惊人的模式匹配器。 不一致会惹恼或分散读者的注意力。 如果我们到处都使用首字母大写，那就使用首字母大写。 如果我们到处都使用结尾逗号，那就使用结尾逗号。 如果所有 Cookbook 笔记本都使用下划线和句子大小写命名，那就使用下划线和句子大小写。 不要做任何会让读者觉得“嗯，这很奇怪”的事情。 帮助他们专注于内容，而不是其不一致之处。
不要告诉读者他们在想什么或该做什么。 避免使用诸如“现在你可能想了解如何调用函数”或“接下来，你需要学习调用函数”之类的句子。 这两个例子都假定了读者的心态，这可能会惹恼他们或损害我们的信誉。 使用避免假设读者状态的短语。 例如，“要调用函数，……”
广泛地提供帮助
人们带着不同程度的知识、语言能力和耐心来阅读文档。 即使我们的目标是经验丰富的开发人员，我们也应该尝试编写对所有人都有帮助的文档。
写得简单点。 解释事情要比你认为需要的更简单。 许多读者可能 не 以英语为母语。 许多读者可能对技术术语感到非常困惑，并且没有多余的脑力来解析英语句子。 写得简单点。（但不要过度简化。）
避免缩写。 把事情写出来。 专家的成本很低，而初学者的收益很高。 不要使用 IF，而要写 instruction following（指令跟随）。 不要使用 RAG，而要写 retrieval-augmented generation（检索增强生成）（或我更喜欢的术语：search-ask procedure（搜索-提问程序））。
为潜在问题提供解决方案。 即使 95% 的读者知道如何安装 Python 包或保存环境变量，主动解释它仍然是值得的。 包含解释对专家来说并不昂贵——他们可以快速浏览过去。 但排除解释对初学者来说代价高昂——他们可能会卡住甚至放弃我们。 请记住，即使是专业的 JavaScript 工程师或 C++ 工程师也可能是 Python 的初学者。 宁可解释得过多，也不要解释得太少。
优先使用具体且准确的术语。 行话是不好的。 为该领域的新手而不是我们自己优化文档。 例如，与其写“prompt”，不如写“input”。 或者与其写“context limit”，不如写“max token limit”。 后者这些术语更不言自明，并且可能比在基础模型时代开发的行话更好。
保持代码示例通用且可导出。 在代码演示中，尽量减少依赖项。 不要让用户安装额外的库。 不要让他们不得不在不同的页面或章节之间来回参考。 尽量使示例简单且自包含。
按价值对主题进行优先级排序。 涵盖常见问题的文档（例如，如何计数令牌）比涵盖罕见问题的文档（例如，如何优化表情符号数据库）价值高得多。 相应地确定优先级。
不要教授不良习惯。 如果 API 密钥不应存储在代码中，则永远不要分享在代码中存储 API 密钥的示例。
以广泛的开场白介绍主题。 例如，如果解释如何编写一个好的推荐器，请考虑在开头简要提及推荐在网络上无处不在，从 YouTube 视频到亚马逊商品再到维基百科。 用广泛的开场白来定位一个狭隘的主题，可以帮助人们在进入不确定的领域之前感到更安全。 如果文本写得好，那些已经了解它的人可能仍然会喜欢它。
当你有充分理由时，打破这些规则
最终，做你认为最好的。 文档是一种同理心的练习。 站在读者的立场上，做你认为最能帮助他们的事情。