文档的目的是将有用的信息传递给其他人。以下是编写更好文档的一些建议。
让文档易于浏览
大多数读者不会从头到尾按顺序阅读文档。他们会跳着看，试图找到能解决自己问题的部分。为了减少他们的搜索时间，提高解决问题的几率，请确保文档易于浏览。
将内容分成有标题的章节。 章节标题就像路标，帮助读者判断是否需要继续阅读。
优先使用描述性句子作为标题，而非抽象名词。 例如，标题 "结果" 并不能直接告诉读者结果是什么，读者需要深入文本才能了解。而如果使用 "流式传输将首次返回令牌的时间减少了50%"，读者可以立刻获得关键信息，而不需要额外的阅读。
包含目录。 目录可以帮助读者更快地找到所需信息，就像哈希表相比链表有更快的查找速度一样。目录还有另一个常被忽视的好处：它为读者提供文档的线索，帮助他们判断是否值得继续阅读。
保持段落简短。 简短的段落更易于浏览。如果有重要信息，可以将其单独放在一个句子的段落中，降低它被忽略的可能性。长段落容易让信息被埋没。
在段落和章节的开头使用简洁的主题句，以提供独立预览。 当人们浏览时，他们会尤其注意段落的第一个词、第一行和第一句。因此这些句子应当独立于之前的文本。例如， "基于此，我们接下来讨论一种更快的方法" 这样的句子对没看过上一段的人来说毫无意义。可以改为 "向量数据库可以加速嵌入搜索"，让其具有独立意义。
将主题词放在主题句的开头。 当读者仅需读一两个词就能了解段落主题时，他们的浏览效率最高。因此，编写主题句时，优先将主题放在句子的开头。例如， "嵌入搜索可以通过向量数据库加速" 不如 "向量数据库加速嵌入搜索" 更利于快速浏览。
将关键信息置于前面。 把最重要的信息放在文档和章节的开头。不要采用苏格拉底式的逐步铺垫。不要先介绍过程再讲结果。
使用项目符号和表格。 列表和表格能使文档更易于浏览，尽量多使用它们。
加粗重要内容。 不要害怕加粗重要内容，以帮助读者找到它们。
写得清楚
写得不好的文档会让读者感到疲惫。通过清晰的写作来减轻读者的负担。
保持句子简单。 把长句拆成短句。删掉副词，删掉不必要的词和短语。如果适用，使用祈使语气。遵循写作书籍中的建议。
写出容易解析的句子。 例如， "标题部分使用句子" 这句话中的 "标题" 读者在读到后无法立刻知道它是名词还是动词，这需要读者多花一些脑力来解析，可能会导致误解。可以使用更容易解析的句子（如 "用句子作为章节标题"），即使它更长。同样，避免使用像 "自行车清理演练通知" 这样费力解析的名词短语。
避免左分支句子。 语言树可以展示单词在句子中的相互关系。左分支句子需要读者记住更多信息，就像广度优先搜索相比深度优先搜索更复杂。例如， "做煎饼需要面粉、鸡蛋、牛奶、黄油和一点盐" 就是左分支句子，因为直到句尾才知道 "需要" 什么。而更容易理解的右分支句子是： "为了做煎饼，你需要面粉、鸡蛋、牛奶、黄油和一点盐"。注意那些需要读者长时间记住某些词的句子，看看能否重新表述它们。
避免使用指示代词（如 "这个"），尤其是跨句子使用。 例如，不要说 "基于我们之前的讨论，现在来讨论函数调用"，而应该说 "基于消息格式化，现在来讨论函数调用"。后者更易理解，因为不需要读者回想之前的内容。尽量减少指示代词的使用，例如直接说 "现在来讨论函数调用"。
保持一致性。 人脑善于模式匹配，不一致的内容会让读者感到烦躁或分心。如果我们在标题中使用大写，那么就保持一致。如果我们在使用逗号时都用结尾逗号，那么就保持一致。如果所有示例代码都用下划线和小写句子结构命名，那么就保持一致。不要让读者有 "咦，这很奇怪" 的感觉，帮助他们集中注意力在内容上，而不是不一致之处。
不要告诉读者他们在想什么或应该做什么。 避免使用 "你可能想知道如何调用一个函数" 或 "接下来你需要学习如何调用一个函数" 这样的句子，它们假设了读者的状态，可能会让他们感到不适或质疑我们的可信度。使用避免假设读者状态的短语，例如 "要调用一个函数，..."。
尽量帮助所有人
不同的读者在阅读文档时，知识水平、语言能力和耐心各不相同。即使我们主要面向有经验的开发者，也应该尽量帮助所有读者。
写得简单。 解释得比你认为需要的更简单。许多读者可能不是以英语为母语，或者在技术术语上感到困惑，解析英语句子时已经没有多余的脑力了。写得简单一点。（但不要过于简化。）
避免使用缩写。 写出完整的词语。对专家来说，额外的阅读成本很低，但对初学者来说，收益很大。例如，不要使用 IF，而要写出 "指令跟随"；不要使用 RAG，而要写出 "检索增强生成"（或我更喜欢的术语： "搜索-提问流程"）。
提供潜在问题的解决方案。 即使 95% 的读者知道如何安装 Python 包或保存环境变量，主动解释一下也还是有价值的。对专家来说，解释是低成本的，他们可以快速浏览过去。但对初学者来说，不解释可能会让他们卡住甚至放弃。记住，即使是专家的 JavaScript 或 C++ 工程师，可能在 Python 上还是初学者。因此，多解释总比解释太少好。
使用具体而准确的术语。 行话会让人费解。将文档优化为针对新手而不是针对我们自己。例如，不要用 "提示"，而用 "输入"；不要用 "上下文限制"，而用 "最大令牌限制"。后者更为直观，也比基础模型时代的行话更好。
让代码示例通用且易于导出。 在代码示例中，尽量减少依赖项，不要让用户安装额外的库，不要让他们需要在不同页面或章节之间来回查找。尽量让示例简单且独立。
按价值优先排序主题。 讲解常见问题的文档（如如何计算令牌数）比讲解罕见问题的文档（如如何优化 emoji 数据库）价值高得多，应该优先安排。
不要教坏习惯。 如果 API 密钥不应存储在代码中，永远不要展示将 API 密钥存储在代码中的示例。
以宽泛的开头引入主题。 例如，如果要解释如何编写一个好的推荐系统，可以先简单提及推荐系统在网络上无处不在，从 YouTube 视频到亚马逊商品再到 Wikipedia 都有推荐。用广泛的内容引入狭窄的主题，可以帮助读者在进入不熟悉的领域前获得安全感。而且，如果文笔优秀，即使已经了解这些内容的人也可能喜欢阅读。
在有充分理由时打破这些规则
最终，做你认为最好的事情。文档的编写是一种共情的练习。
站在读者的角度，做你认为对他们最有帮助的事情。