原文出处：What Makes Documentation Good 原作者：OpenAI · 许可证：MIT License 中文译本由诸葛AI学院整理，仅供学习参考，版权归原作者与 OpenAI 所有。

什么样的文档是好文档

文档做的事，是把有用的信息装进别人的脑子里。照着下面的建议写，文档会更好。

让文档方便扫读

很少有人从头到尾按顺序读。读者会跳来跳去，想找出哪一段能解决自己的问题，也可能一段都对不上。想缩短他们的寻找时间、提高他们找到答案的概率，就得让文档方便扫读。

把内容切成带标题的小节。 小节标题像路牌，告诉读者是该停下来细读，还是继续往下看。

标题用信息完整的句子，别用抽象名词。 比如拿"结果"当标题，读者得跳进正文才知道结果到底是什么。要是把标题写成"流式输出（streaming）把等待首个字块（token）的时间缩短了 50%"，读者一眼就拿到信息，不用再多跳一步。

附上目录。 目录能让读者更快找到信息，就像哈希表（hash map）的查找比链表（linked list）快。目录还有一个常被忽略的好处：它给读者提供线索，帮他们判断这篇文档值不值得读。

段落要短。 段落越短越好扫读。如果你有非说不可的要点，考虑把它单独成段、只写一句话，降低被漏掉的概率。长段落会把信息埋起来。

段落和小节的开头放一句短的主题句，能独立给出预览。 人们扫读时，注意力会不成比例地落在第一个词、第一行和小节的第一句话上。这些句子要写成不依赖前文也能看懂。举个例子，假如第一句是"在这个基础上，我们再来谈一个更快的办法"，没读过上一段的人会被搞得莫名其妙。应该改成独立可懂的写法，比如："向量数据库（vector database）能加快嵌入（embedding）检索。"

把主题词放在主题句开头。 读者只需读一两个词就知道段落大意时，扫读效率最高。所以写主题句时，主题放句首，别放句尾。比如你在一篇讲嵌入检索的长文章中间写一段向量数据库，与其写"嵌入检索可以由向量数据库来加速"，不如写"向量数据库加速嵌入检索"。后一句更适合扫读，因为段落主题落在了段首。

把结论放在最前面。 最重要的信息放在文档和小节的开头。别做苏格拉底式的层层铺垫，别在讲结果之前先讲过程。

多用列表和表格。 项目符号列表和表格让文档更好扫读，要多用。

给重要的文字加粗。 别舍不得加粗，它能帮读者定位重点。

把文字写好

写得差的文字，读起来费人。把文字写好，读者的负担就小。

句子保持简单。 长句拆成两句。删掉副词。删掉不需要的词和短语。能用祈使句就用祈使句。写作书里讲的规矩照做就行。

写不会被误读的句子。 比如 "Title sections with sentences."（用句子给小节起标题）这句英文：读者读到 "title" 这个词时，大脑还不知道它接下来是名词、动词还是形容词。解析后半句时得占着一份脑力去跟踪，一旦猜错意思就会卡壳。优先选更容易解析的写法，比如 "Write section titles as sentences"，哪怕句子更长。同理，避开 "Bicycle clearance exercise notice" 这类名词堆出来的短语，解析它们要多费力气。

避免左分支句。 语言学的树状图展示句子中词语之间的修饰关系。左分支句（left-branching）比重右分支句（right-branching）要读者在记忆里悬着更多内容，就像广度优先搜索和深度优先搜索的差别。左分支句的例子："You need flour, eggs, milk, butter and a dash of salt to make pancakes."（做薄饼，你需要面粉、鸡蛋、牛奶、黄油和一小撮盐。）在这句里，你要读到句尾才知道 "you need" 到底连着什么。更好读的右分支写法是："To make pancakes, you need flour, eggs, milk, butter, and a dash of salt."。留意那些让读者长时间悬着一个词的句子，试着换个说法。

少用指示代词（如 "this"），尤其是跨句指代。 比如，别说"基于我们刚才讨论的上一个话题，现在来聊聊函数调用（function calling）"，可以说"聊完消息格式（message formatting），现在说说函数调用"。后一句更好懂，因为读者不用费力回忆上一个话题。有机会就干脆把指示代词整个删掉，比如直接说："现在说说函数调用。"

保持一致。 人脑是出色的模式识别器，前后不一致会让读者烦躁或分心。如果通篇用标题式大写（Title Case），就一直用它；如果列表项末尾都带逗号，就都带上；如果 Cookbook 的笔记本全部用下划线加句首大写命名，就照这个规矩来。别让读者冒出"咦，好奇怪"的念头。帮他们把注意力放在内容上，而不是格式的不一致上。

别替读者宣布想法，也别命令他们该做什么。 避免"你现在大概想搞懂怎么调用函数""接下来你得学会调用函数"这类句子。两个例子都在揣测读者的心理状态，可能惹恼读者，也可能消耗我们的可信度。换成不预设读者状态的写法，例如："要调用函数，……"

对尽可能多的人有用

读者带着不同的知识水平、语言能力和耐心来到文档面前。哪怕目标读者是有经验的开发者，也要尽量把文档写得对所有人都有用。

写得简单。 解释得比你以为需要的再简单一点。很多读者母语不是英语；很多读者本来就对技术术语发怵，没有多余的脑力去啃英语句子。写得简单。（但别简化到失真。）

不用缩写。 把词写全。这对专家没什么成本，对新手好处很大。别写 IF，写"指令遵循（instruction following）"；别写 RAG，写"检索增强生成（retrieval-augmented generation）"，或者用我更喜欢的说法："搜索-提问"流程。

预判问题，给出解法。 哪怕 95% 的读者都知道怎么安装 Python 包、怎么保存环境变量，主动解释一下也值得。多写解释不伤专家，他们一眼就能扫过去；少写解释会伤新手，他们可能卡住，甚至干脆弃我们而去。记住，即便是资深的 JavaScript 或 C++ 工程师，也可能是 Python 新手。宁可多解释，不要少解释。

用具体、准确的术语。 行话不好。文档要服务刚入行的人，而不是服务我们自己。比如，与其写"提示词（prompt）"，不如写"输入（input）"；与其写"上下文限制（context limit）"，不如写"最大字块上限（max token limit）"。后一种说法一目了然，多半比基础模型时代留下来的行话更好。

代码示例保持通用、可搬走。 写演示代码时尽量少依赖。别让用户额外装库，别让他们在不同页面或小节之间来回翻。示例尽量简单、自包含。

按价值排选题的优先级。 讲常见问题的文档（比如怎么统计字块数量），比讲罕见问题的文档（比如怎么优化一个表情符号（emoji）数据库）有价值得多。排优先级时照这个来。

别教坏习惯。 如果 API 密钥（API key）不该存在代码里，那就永远不要给出把密钥写进代码的示例。

用宽泛的开场引出话题。 比如，讲怎么写好一个推荐系统（recommender），开头可以先提一句：推荐在整个互联网上无处不在，从 YouTube 视频到亚马逊商品再到维基百科。用宽泛的开场给狭窄的话题打个地基，能让读者在跳进陌生领域前心里更有底。文字写得好，已经懂这些的读者也照样爱看。

有正当理由就打破这些规则

说到底，按你自己认为最好的来。文档写作是一种共情练习。把自己放到读者的位置上，做你认为对他们帮助最大的事。