文档的作用是将有用的信息传递到他人的脑海中。遵循这些技巧来撰写更优质的文档。
让文档易于浏览
很少有读者会从头到尾线性阅读文档。他们会快速浏览，试图找到能解决他们问题的部分（如果有的话）。为了减少他们的搜索时间并提高成功几率，请确保文档易于浏览。
将内容划分为带标题的章节。 章节标题如同路标，指引读者决定是深入阅读还是继续浏览。
标题应使用信息丰富的句子，而非抽象名词。 例如，如果使用"Results"这样的标题，读者需要跳转到后续文本才能了解具体结果。相反，如果使用"流式处理将首个令牌时间缩短50%"这样的标题，就能立即为读者提供信息，无需额外跳转。
包含目录。 目录能帮助读者更快找到信息，就像哈希表比链表查询速度更快一样。目录还有第二个常被忽视的好处：它们为读者提供文档内容的线索，帮助判断是否值得阅读。
保持段落简短。 短段落更便于快速浏览。如果有重要观点，可以考虑将其单独成段（甚至一句话一段），以降低被忽略的概率。冗长的段落容易掩盖关键信息。
段落和章节应以简短的主题句开头，提供独立的预览。 当人们浏览时，他们会不成比例地关注章节的第一个词、第一行和第一句话。这些句子应以不依赖前文的方式撰写。例如，考虑第一句话"在此基础上，我们现在来讨论一种更快的方法。" 对于没有阅读前一段的读者来说，这句话毫无意义。相反，应以独立可理解的方式撰写：例如，"向量数据库可以加速嵌入搜索。"
将主题词放在主题句的开头。 当读者只需阅读一两个词就能了解段落内容时，他们的浏览效率最高。因此，在撰写主题句时，建议将主题放在句首而非句尾。例如，假设您正在一篇关于嵌入搜索的长文中撰写关于向量数据库的段落。与其写"嵌入搜索可以通过向量数据库加速"，不如写"向量数据库能加速嵌入搜索"。第二句话更便于浏览，因为它将段落主题放在了段落的开头。
将要点前置。 将最重要的信息放在文档和章节的开头。不要采用苏格拉底式的长篇铺垫。不要在展示结果之前先介绍你的流程。
使用项目符号和表格。 项目符号列表和表格能让文档更易于浏览。请多加使用它们。
加粗重要文本。 不要害怕将重要文本加粗，以帮助读者找到它。
写出好文章
写得糟糕的文字读起来很费劲。通过良好的写作来减轻读者的负担。
保持句子简洁。 将长句拆分为两句。删减副词。去除不必要的词语和短语。如适用，使用祈使语气。遵循写作指南的建议。
撰写能够明确解析的句子。 例如，考虑句子“用句子为章节添加标题”。当读者读到“Title”这个词时，他们的大脑尚不确定“Title”将作为名词、动词还是形容词使用。在解析句子其余部分时，这会消耗一定的脑力，如果大脑对含义预测错误，还可能导致理解障碍。应优先选择更易于解析的句子（例如“将章节标题写成句子”），即使句子更长也无妨。同样，应避免使用像“自行车间隙练习通知”这样的名词短语，这类短语需要额外精力来解析。
避免使用左分支句式。 语言树展示了句子中词语之间的关联。相比右分支句式，左分支句式要求读者在记忆中暂存更多信息，类似于广度优先搜索与深度优先搜索的区别。一个左分支句式的例子是："制作煎饼需要面粉、鸡蛋、牛奶、黄油和少许盐。"在这个句子中，直到句末读者才能明白"需要"连接的内容。更易读的右分支版本是："要制作煎饼，你需要面粉、鸡蛋、牛奶、黄油和少许盐。"注意那些要求读者长时间记住某个词的句子，并尝试重新表述它们。
避免使用指示代词（如“这个”），尤其是在跨句子时。 例如，不要说“基于我们之前讨论的主题，现在让我们讨论函数调用”，而应该说“基于消息格式，现在让我们讨论函数调用”。第二句话更容易理解，因为它不需要读者回忆之前的话题。寻找机会完全省略指示代词：例如，“现在让我们讨论函数调用”。
保持一致性。 人类大脑是出色的模式识别器。不一致性会令读者感到困扰或分心。如果我们统一使用标题大写，就请始终使用标题大写；如果我们统一采用末尾逗号，就请始终使用末尾逗号；如果所有Cookbook笔记本都采用下划线和句子式命名，就请统一使用下划线和句子式命名。不要做出任何让读者产生"咦，这很奇怪"反应的行为。帮助读者专注于内容本身，而非其中的不一致性。
不要告诉读者他们应该怎么想或怎么做。 避免使用诸如"现在你可能想了解如何调用函数"或"接下来你需要学习调用函数"这样的句子。这两个例子都假设了读者的心理状态，这可能会让他们感到恼火或损害我们的可信度。使用避免假设读者状态的措辞，例如"要调用函数，..."
广泛提供帮助
人们查阅文档时的知识水平、语言熟练度和耐心程度各不相同。即使我们的目标用户是经验丰富的开发者，也应尽量编写对所有人都有帮助的文档。
简洁写作。 解释时要比你认为必要的更简单。许多读者可能不以英语为母语。许多读者可能对技术术语感到非常困惑，没有多余的脑力来解析英语句子。写作要简洁。（但不要过度简化。）
避免使用缩写。 完整拼写出来。对专家来说成本很低，但对初学者来说收益很大。不要用IF，而是用instruction following（指令跟随）。不要用RAG，而是用retrieval-augmented generation（检索增强生成，或我偏好的术语：搜索-询问流程）。
Offer solutions to potential problems. Even if 95% of our readers know how to install a Python package or save environment variables, it can still be worth proactively explaining it. Including explanations is not costly to experts—they can skim right past them. But excluding explanations is costly to beginners—they might get stuck or even abandon us. Remember that even an expert JavaScript engineer or C++ engineer might be a beginner at Python. Err on explaining too much, rather than too little.
优先使用具体且准确的术语。行话不好。文档应针对该领域的新手优化，而非我们自己。例如，与其写"prompt"，不如写"输入"；与其写"context limit"，不如写"最大token限制"。后者的含义更不言自明，可能比基础模型时代形成的行话更好。
保持代码示例通用且可导出。 在代码演示中，尽量减少依赖项。不要让用户安装额外的库。不要让他们在不同页面或章节之间来回翻阅。尽量使示例简单且自包含。
按价值优先排序主题。 涵盖常见问题的文档（例如如何计算token数量）其价值远高于涉及罕见问题的文档（例如如何优化表情符号数据库）。请据此进行优先级排序。
不要教授不良习惯。 如果API密钥不应存储在代码中，就永远不要分享将API密钥存储在代码中的示例。
以宽泛的开场介绍主题。 例如，如果要解释如何编写一个好的推荐系统，可以考虑先简要提及推荐在网络上无处不在，从YouTube视频到亚马逊商品再到维基百科。用一个宽泛的开场来铺垫一个狭窄的主题，可以帮助人们在进入未知领域前感到更安心。而且如果文本写得好，即使已经了解的人也可能乐在其中。
在有充分理由时打破这些规则
最终，做你认为最好的选择。文档编写是一种换位思考的实践。站在读者的角度，做你认为最能帮助他们的工作。