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