这是一篇来自OpenAI的英文文章，原文链接https://github.com/openai/openai-cookbook/blob/main/articles/what_makes_documentation_good.md
虽然文章的内容更多是在讲“如何写一篇好的技术类文档”，但是我觉得把它作为”如何写一篇好文章“的建议也是很有用的。所以我用AI把它翻译成中文，留在自己的博客里，作为一个记录。
文档的意义在于——把有用的信息装进别人的脑袋里。要写出真正有用的文档，可以参考以下这些建议。
一、让文档更容易被「扫读」
大多数人阅读文档时不会从头到尾逐字细读，他们会快速跳读，只想找到能解决问题的那一部分。 要减少他们的搜索时间、提高他们成功找到答案的概率，就要让文档便于扫读。
1. 用标题分段。
标题就像路标，能让读者判断「这段我该看」还是「可以跳过」。
2. 用有信息量的标题，而不是抽象名词。
比如标题写“结果（Results）”，读者还得往下看才能知道具体结果是什么。 如果改成“流式输出将首个Token生成时间减少了50%”，读者在标题处就已经得到了核心信息，不必再多跳一步。
3. 加上目录。
目录能让人更快定位信息，就像哈希表查找比链表更快。
另外一个被忽视的好处是：目录能帮助读者判断文档是否值得细读。
4. 保持段落简短。
短段落更容易扫读。关键句子可以单独成段，避免被埋在长文里。
5. 段首要有独立的主题句。
人们在扫读时，注意力往往集中在每段的第一行、第一句。 主题句应该能单独成立，不依赖上一段。
比如别写“在此基础上，我们再来看一种更快的方法”， 改成“向量数据库能加快Embedding搜索速度”， 这样即使没读前文，也能立刻理解。
6. 把主题词放在句首。
读者扫读时通常只看开头几个字。 比如与其写“Embedding搜索可以通过向量数据库加速”， 不如写“向量数据库能加速Embedding搜索”。 主题在前，更利于快速识别。
7. 重点结论放前面。
在文档和章节的开头就写出最重要的信息。 不要绕圈铺垫，也不要先写过程、后写结果。
8. 多用列表和表格。
列表和表格能显著提升可扫读性，多用它们。
9. 重要信息加粗。
不要害怕使用加粗，这能帮读者迅速抓住重点。
二、写得通顺
糟糕的文字让阅读变成负担。写得好，是对读者的尊重。
1. 句子要简单。
- 长句拆成两句。
- 删副词。
- 删多余的词。
- 能用祈使句就用祈使句。
就像写作书上教的那样。
2. 写出语义明确的句子。
比如句子“Title sections with sentences.”
读到“Title”时，大脑还不知道它是名词还是动词，要花额外精力解析。 换成“Write section titles as sentences”更清晰，即使稍长。
同样要避免像“Bicycle clearance exercise notice”这种名词堆砌的结构。
3. 避免左支句。
左支句让读者要在脑中暂存更多信息。 例如：“你需要面粉、鸡蛋、牛奶、黄油和一点盐来做煎饼。” 直到句尾才知道“你想要做”什么。
改成右支句：“要做煎饼，你需要面粉、鸡蛋、牛奶、黄油和一点盐。” 更轻松易懂。
留意那些让读者“等结尾才明白”的句子，尽量重写。
4. 避免使用指示代词（如this、that）跨句指代。
比如别写“基于前一节的讨论，我们来看函数调用”， 而是写“基于消息格式化部分，我们来看函数调用”。
前者需要读者回忆上下文，后者更直接。
5. 保持一致。
人类天生是模式识别机器。风格不一致会让人分神。
比如：如果标题都用首字母大写（Title Case），那就一直这样。如果列表都用结尾逗号，就保持一致。
一致性让读者专注于内容，而不是被格式分散注意力。
6. 不要替读者下判断或安排行为。
像“现在你可能想了解如何调用函数”或“接下来你需要学习如何调用函数”
这类话会让人反感。改成“要调用函数，请……”更自然也更客观。
三、要真正「有帮助」
读者的知识水平、语言能力和耐心都不同。 即使目标读者是经验丰富的开发者，也要尽量让文档对所有人友好。
1. 用更简单的方式解释。
很多人的母语可能与你不同，或者对技术术语还没搞清楚。
写得简单，不会掉价，但是不要过度简化，简化与简单不是一个概念。
2. 避免缩写。
写出术语的全名。
对专家来说多看几个字无妨，但对新手帮助巨大。
比如不要写“RAG”，写“检索增强生成（Retrieval-Augmented Generation）”或“搜索-提问（Search-Ask）流程”。
3. 主动解决潜在问题。
即使95%的读者会安装Python包，也值得说明安装方法。
专家可以直接跳过，新手却可能因此少踩坑。
记住：一个C++高手可能是Python新手。
宁可解释得多，也不要漏讲关键细节。
4. 用具体准确的术语。
根据文章面对的读者的类型。如果是面对普通用户，那就减少行话。优化给新手看，而不是给自己看。
比如，别写“context limit”，而是写“最大token限制（max token limit）”。后者更直观。
5. 代码示例要通用、可直接运行。
示例越独立越好，不要让用户还得装一堆库或来回翻页。
6. 优先写高价值主题。
解释“如何统计token数量”的文档，比“如何优化emoji数据库”的文档有用得多。 优先写常见问题。
7. 不要教坏习惯。
如果API密钥不该写在代码里，那就绝不要在示例里这么做。
8. 以广阔的开头引入主题。
比如在介绍推荐系统前，可以先提到它在YouTube、亚马逊、维基百科等场景的应用。 这种铺垫能让读者更安心地进入主题。
写得好的人，即使已经懂，也会觉得读起来顺。
四、打破规则也没关系
所有规则都不是死的。 写文档是一种同理心的练习——站在读者角度思考，
重要 问自己：怎样写，才能最真诚、最高效地帮助他们？