工作后会发现写作能力是每个行业最基础也是最重要的能力之一，因为在很多场景下你想要清晰地阐述你的观点和想法给其他人，离不开你的写作能力；当然很多时候传播的方式除了文字，还有口述等方式，这些都离不开语言组织和逻辑思维能力，而这些能力与写作能力的相关性是极高的，某种程度上写作能力只是这些能力的表达方式，它们均是一脉相承。
而文档能力也属于写作能力的一种，文档能力对严谨性，专业性，准确性要求更高。对于程序员而言，开发或者维护一个系统如果没有配套的官方文档那么这个项目可能只会是个人的自娱自乐，很难被广泛传播使用和传承。正所谓酒香也怕巷子深，有好的文档能力，才能更好地宣传产品，品牌与技术。
下面是OpenAI的文章**《What makes documentation good》** 的翻译，介绍了如何写出好的文档，与大家一起学习提升自己的文档撰写能力！
文档将有用的信息展示给他人，请遵循这些建议来编写更好的文档。
一、让文档便于快速浏览（Make docs easy to skim）
大多数读者并不会从头到尾、顺序阅读。他们会跳来跳去，尝试判断哪一部分能解决自己的问题。
因此，为了减少他们查找信息的时间、提高成功率，我们应该让文档"易于快速浏览"。
✅ 可做的措施
-
**将内容拆分为多个章节，并给每章加上标题。**标题像路标一样，告诉读者"我是否应该看这里，或者跳过"。
-
**标题最好用"说明性句子"而不是抽象名词。**例如，与其用 "Results"（结果）作为标题，不如用 "Streaming reduced time to first token by 50%"（流式传输将首次 token 的时间减少了 50%）作标题，因为后者一眼就让读者明白本节在讲什么。
-
**包含目录（Table of Contents）。**目录帮助读者更快定位，就像散列表查找比链表快。此外，目录还能给出文档整体的提示，让读者判断是否值得阅读。
-
**保持段落短小。**短段落更易被扫描。如果有一个关键点，考虑把它单独放在一句话的段落里。长段落容易将信息埋没。
-
**段落或章节开头应有一个简短的主题句，能独立传达本段主要内容。**因为在快速浏览时，读者会特别注意每段的第一句话。不能写"在前面我们讨论了...现在我们来..." 这种依赖上文的话。比如，把"向量数据库可以加快 embeddings 搜索"放在首句，而不是"建立在此基础上，我们现在来谈一谈更快的方法"。
-
**在主题句中，把主题词放在句首。**读者在快速浏览时，希望一眼就知道这个段落在讲什么。比如：
-
不首选"Embeddings search can be sped up by vector databases"
-
首先用 "Vector databases speed up embeddings search"，主题词 "Vector databases" 放在了句首，更方便读者阅读。
-
-
**将"结论／关键收获"提前放在文档或章节最前面。**不要先铺陈一堆上下文再慢慢引出结果。
- **使用项目符号和表格。**列表和表格让文档更利于快速浏览。
- 加粗重要文字 **。**不要害怕加粗，加粗可以帮助读者定位重要信息。
二、写得好（Write well）
写得差劲的文档会加重读者负担。我们应尽量减少读者"读懂文档"所需的脑力负担。
✅ 写作方面的建议
- **句子保持简单。**把长句切成两句。删掉副词、不必要的词语和短语。用祈使语气（如果适用）。就像写作书籍建议的那样。
- 写那些易于无歧义理解 **的句子。**例如：句子"Title sections with sentences." 读者看到"Title"时，不知道这"Title"是名词、动词还是形容词，心里会迷糊。相比之下，"Write section titles as sentences"虽然稍长，但结构清晰。
-
**避免"左分支"句子（left-branching sentences），**即那种读者在读句子的前半段就要记住很多东西，再等到后半句才知道主干。举例："You need flour, eggs, milk, butter and a dash of salt to make pancakes." 就是典型左分支。可以改为 "To make pancakes, you need flour, eggs, milk, butter, and a dash of salt." 这样右分支更易读。
-
**避免使用指示代词（如 "this"）跨句子模糊地指代上文。**例如，不要写 "Building on our discussion of the previous topic, now let's discuss function calling"， 而应写"Building on message formatting, now let's discuss function calling"，后者一看就知道"message formatting"是什么，而不用读者回头猜。
-
**保持风格一致。**人脑擅长识别模式。不一致的风格会让读者觉得"咦，这哪儿怪怪的"。例如，如果你一直用标题大小写（Title Case），就一直用；如果你在代码示例里变量名用不同格式，就会让人心烦。
-
**不要假定读者的心理状态或行为。**避免写 "Now you probably want to understand..." 或"Next, you'll need to learn..."这类假设性的句子，因为并不是每个读者"可能"或"下一步"都跟你想的一样。改写为 "To call a function, ..."这样的陈述句。
三、广泛地提供帮助（Be broadly helpful）
读文档的人背景各不相同：知识水平不同、语言能力不同、耐心也不同。即便我们面向的是经验丰富的开发者，也应努力把文档写得对所有人都有帮助 。
✅ 实践建议
-
写得简单 **。**用比你认为需要还要更简单的方式解释。许多读者可能英语不是母语，很多人可能对技术术语已经困惑、几乎没有额外的脑力去理解复杂句子，所以要写得简单（但不要过度简化）。
-
**避免缩写。**写出完整词语。对专家而言成本很低、但对初学者帮助很大。比如，不用 "IF"，而是 "instruction following"；不要写"RAG"，而是"retrieval-augmented generation (或我喜欢的说法: search-ask procedure)"。
-
**提供可能出现的问题的解决方案。**即使95%的读者知道如何安装Python 包或设置环境变量，主动解释也可能值得。专家可以快速跳过；但如果你省略，初学者可能就卡住、甚至放弃。记住：即便是一个精通JavaScript或C++的工程师，也可能在Python领域是初学者。宁可多解释一点，也不要少。
-
术语要具体且准确 **。**行话（jargon）对读者可能不太友好。把文档优化给"对这个领域是新手"的人，而不是你自己。例如，不要写"prompt"，而写 "input"；不要写"context limit"，而写"max token limit"。后者更直观、更可能比早期基础模型时代的行话来得好。
-
**保持代码示例 "通用且可导出"。**在代码演示时，尽量减少依赖。不要让用户必须安装额外库，不要让他们必须在不同页面或章节间来回查找。尽量使示例简单、自成一体。
-
按价值优先排序 **内容。**文档中覆盖常见问题（例如：如何计数tokens）比覆盖极少见问题（例如：如何优化一个emoji数据库）价值大得多。优先考虑读者最常遇到的问题。
-
不要教不好的习惯 **。**例如如果API密钥不该写到代码里，就永远不要在示例里那样写，防止误导读者。
-
引入主题时用一个广泛的开场**** **。**比如，如果你要解释如何设计一个推荐系统，可以先提及推荐系统在网页、YouTube视频、Amazon商品、Wikipedia 条目中的广泛应用。用广义开场帮助读者建立安全感，然后再进入狭义主题。如果写得好，那些已经知道背景的人也会觉得"嗯，还不错"。
四、当你有充分理由时，可以****破例（Break these rules when you have a good reason）
最终，你要做的是"为读者做最有帮助的事"。文档写作是一种"共情练习"。设身处地为读者思考，然后做出你认为最能帮助他们的选择。
五、总结
-
优秀文档易于快速浏览：清晰的标题、短段落、早揭结论、项目符号／表格。
-
写作上要简洁、清晰、避免复杂句式或行话。
-
面向广泛读者：用简单语言、避免缩写、解决常见问题、提供自成一体的代码示例。
-
**不要教不好的习惯。**优先帮助读者常见的问题。
-
虽有规则，但不是禁锢**。如果你有充分理由** 破例，也没关系；关键是为"读者的利益"服务。