一、让文档易于浏览
-
分段与标题 把内容分成有标题的部分。标题就像路标，告诉读者该专注于哪里，或者是否该跳过。
-
信息型标题优于抽象名词 优先使用“信息型标题”而非“抽象名词”标题。 例如：
- 不佳示例：“结果”
- 更好示例：“流式处理将首个 token 时间减少了 50%”
-
添加目录 目录能让读者更快找到信息，就像哈希表查找比链表快。 同时，目录能让读者对文档内容形成预期，从而判断是否值得阅读全文。
-
段落要短 短段落更容易浏览。重要内容可独立成段，用一句话突出。长段落会掩埋重点。
-
开头句要有主题感 每个段落或章节开头写简短的主题句，让它能独立概述内容。 示例：
- 不佳：“基于以上，我们来谈谈更快的方法。”
- 更好：“向量数据库可以加速嵌入搜索。”
-
主题词置于句首 把主题词放在句子最前面，让读者快速判断段落内容。 示例：
- 不佳：“嵌入搜索可以通过向量数据库加速。”
- 更好：“向量数据库加速嵌入搜索。”
-
结论先行 把最重要的信息放在文档和每节的开头。不要先讲过程再讲结果。
-
善用列表与表格 项目符号与表格能显著提高可浏览性，要常用。
-
加粗重点 不要害怕使用粗体，帮助读者快速定位关键信息。
二、写得好
-
保持句子简洁 长句拆开；删副词；删掉冗余词；能用祈使句就用祈使句。
-
句子应易于解析 避免歧义结构。 示例：
- 不佳：“Title sections with sentences.”
- 更好：“Write section titles as 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、that） 不要依赖读者回忆上文。 示例：
- 不佳：“Building on our discussion of the previous topic…”
- 更好：“Building on message formatting…”
-
保持一致性 格式统一，风格一致。不要让读者冒出“咦，这不对劲”的念头。 例如：标题格式、标点用法、命名方式都要保持一致。
-
不要假设读者心态 避免写“你现在可能想知道……”这类句子。 改写为中性表达：“要调用函数，……”
三、做到普遍有用
-
写得简单 比你认为必要的还要简单。考虑非英语母语读者或技术新手。
-
避免缩写 完整拼写术语。 示例：
- IF → instruction following
- RAG → retrieval-augmented generation（或更明晰的 “search-ask procedure”）
-
提供潜在问题的解决方案 即使 95% 的人会安装包或设置变量，也值得说明。对专家无碍，对新手帮助巨大。
-
用具体准确的术语 减少行话。 示例：
- “输入” 比 “提示词” 更清晰
- “最大 token 限制” 比 “上下文限制” 更直观
-
保持代码示例通用且可复用 减少依赖、避免额外安装、示例自洽。
-
按价值优先排序 常见问题（如计数 token）远比罕见问题（如优化 emoji 数据库）更有价值。
-
不传递坏习惯 如果 API key 不该出现在代码中，示例里也不要出现。
-
用宏观引入开场 介绍具体技术前，先讲通用背景。 例如在讲推荐系统时，先提 YouTube、Amazon、Wikipedia 等应用场景。
四、当有充分理由时，打破规则
归根结底，做你认为最有帮助的事。 写文档是一种共情练习——设身处地为读者着想，做能让他们最受益的事。
