如何撰写优质文档

文档是将有用信息植入他人脑海的过程。遵循以下建议，提升你的文档写作水平。

使文档易于浏览

很少有读者会从上到下线性地阅读文档。他们通常会跳跃阅读，试图判断哪部分内容能解决他们的问题，如果有的话。为了减少他们的搜索时间并提高成功率，应使文档易于浏览。

将内容分割成带有标题的章节。 章节标题如同路标，告诉读者是否应深入阅读或继续前进。

标题应使用信息丰富的句子而非抽象名词。 例如，使用“结果”作为标题，读者需要跳入下文才能了解具体结果是什么。相比之下，“流式处理将首次令牌时间缩短了50%”这样的标题，能让读者立即获取信息，无需额外跳转。

包含目录。 目录帮助读者更快找到信息，类似于哈希表比链表查找更快。目录还有第二个常被忽视的好处：它们为读者提供文档内容的线索，帮助他们判断是否值得阅读。

保持段落简短。 短段落更易于浏览。如果有重要观点，考虑将其单独放在一个句子段落中，以降低被忽略的概率。长段落可能会掩盖信息。

段落和章节开头使用简短的主题句进行独立预览。 人们在浏览时，会 disproportionately 关注章节的首词、首行和首句。撰写这些句子时，应使其不依赖于前文。例如，“在此基础上，让我们现在讨论一个更快的方法。”这句话对未读前段的人毫无意义。相反，应写成独立可理解的形式：如，“向量数据库能加速嵌入搜索。”

将主题词置于主题句开头。 读者在只需阅读一两个词就能了解段落内容时，浏览效率最高。因此，撰写主题句时，应将主题置于句首而非句尾。例如，在长篇关于嵌入搜索的文章中写到向量数据库时，不要写“嵌入搜索可通过向量数据库加速”，而应写“向量数据库加速嵌入搜索”。第二句更适合浏览，因为它将段落主题置于段落开头。

将要点前置。 将最重要的信息置于文档和章节顶部。不要采用苏格拉底式的逐步构建。不要在结果之前介绍过程。

使用项目符号和表格。 项目列表和表格使文档更易于浏览。应频繁使用。

加粗重要文本。 不要害怕加粗重要文本以帮助读者找到它。

写作要精炼

糟糕的文本阅读起来费力。通过精炼写作，减少读者的阅读负担。

保持句子简洁。 将长句拆分为两个。删去副词。删去不必要的词和短语。如果适用，使用祈使语气。遵循写作书籍的建议。

撰写可明确解析的句子。 例如，考虑句子“用句子作为章节标题。”当读者读到“标题”这个词时，他们的大脑尚未确定“标题”是名词、动词还是形容词。在解析句子的其余部分时，需要一定的脑力来跟踪，如果大脑预测的意义错误，可能会造成停顿。应倾向于更易解析的句子（如，“将章节标题写成句子”），即使较长。同样，避免使用如“自行车清仓练习通知”这样的名词短语，它们解析起来需要额外努力。

避免左分支句式。 语言树展示了句子中词语之间的关系。左分支树要求读者记忆的信息多于右分支句式，类似于广度优先搜索与深度优先搜索。左分支句式的一个例子是“制作煎饼需要面粉、鸡蛋、牛奶、黄油和少许盐。”在这句话中，直到句子结束你才知道“你需要”连接的是什么。一个更易读的右分支版本是“制作煎饼，你需要面粉、鸡蛋、牛奶、黄油和少许盐。”注意那些读者必须长时间记住某个词的句子，并尝试重新表述。 避免使用指示代词（例如，“这个”），尤其是在句子之间。 例如，不要说“基于我们之前话题的讨论，现在让我们讨论函数调用”，而应该说“基于消息格式化，现在让我们讨论函数调用。” 第二个句子更容易理解，因为它不需要读者回忆之前的话题。寻找机会完全去掉指示代词：例如，“现在让我们讨论函数调用。”

保持一致性。 人类大脑是惊人的模式匹配器。不一致性会让读者感到烦恼或分心。如果我们到处使用标题大写，就使用标题大写。如果我们到处使用终端逗号，就使用终端逗号。如果所有 Cookbook 笔记本都用下划线和句子大小写命名，就使用下划线和句子大小写。不要做任何会让读者觉得“嗯，这很奇怪”的事情。帮助他们专注于内容，而不是其不一致性。

不要告诉读者他们的想法或该做什么。 避免使用诸如“现在你可能想了解如何调用函数”或“接下来，你需要学习如何调用函数”这样的句子。这两个例子都假设了读者的思维状态，这可能会让他们感到烦恼或损害我们的可信度。使用不假设读者状态的短语。例如，“要调用函数，...”

广泛有益

人们带着不同水平的知识、语言能力和耐心来到文档。即使我们针对有经验的开发者，也应该尝试编写对每个人都友好的文档。

简单写作。 解释事情比你认为需要的更简单。许多读者可能不是以英语为母语。许多读者可能对技术术语非常困惑，几乎没有多余的脑力来解析英语句子。简单写作。（但不要过度简化。）

避免缩写。 写出全称。对专家的成本很低，对初学者的益处很高。不要用 IF，写成 instruction following。不要用 RAG，写成 retrieval-augmented generation（或我喜欢的术语：搜索-询问程序）。

提供潜在问题的解决方案。 即使 95% 的读者知道如何安装 Python 包或保存环境变量，主动解释它仍然有价值。包括解释对专家来说成本不高——他们可以快速略过。但不包括解释对初学者来说成本很高——他们可能会卡住甚至放弃我们。记住，即使是专家级的 JavaScript 或 C++ 工程师也可能是 Python 的初学者。宁可解释太多，也不要太少。

偏好具体和准确的术语。 行话不好。优化文档给领域新手，而不是我们自己。例如，不要写“prompt”，写成“input”。或者不要写“context limit”，写成“max token limit”。后者的术语更自明，可能比基础模型时代的行话更好。

保持代码示例通用和可导出。 在代码演示中，尽量减少依赖。不要让用户安装额外的库。不要让他们必须在不同页面或部分之间来回参考。尽量使示例简单和自包含。

按价值优先排序主题。 涵盖常见问题的文档——例如，如何计数令牌——比涵盖罕见问题的文档——例如，如何优化表情符号数据库——价值大得多。相应地优先排序。

不要教坏习惯。 如果 API 密钥不应该存储在代码中，永远不要分享一个存储 API 密钥的示例。

广泛开场介绍主题。 例如，如果解释如何编程一个好的推荐器，可以先简要提及推荐在网络上的广泛应用，从 YouTube 视频到亚马逊商品到维基百科。用广泛的开口来定位狭窄的主题可以帮助人们在跳入不确定领域之前感到更安全。如果文本写得好，那些已经知道的人可能仍然会喜欢它。

有充分理由时打破这些规则

最终，做你认为最好的。文档是同理心的练习。设身处地为读者着想，做你认为对他们最有帮助的事情。