文档的作用，是把有用的信息塞进别人的脑袋。想让文档真正好用，不妨记住下面这些小窍门。
先让“扫读”变轻松几乎没人会从第一行乖乖读到最后一行。大家像跳房子一样东瞄西看，只想快点确认这段文字能不能解决自己的问题。所以，降低他们的搜索成本，就是提高成功率的捷径。
• 切块 + 小标题
把内容切成小段，每段配一个“一眼能懂”的小标题。标题别玩抽象，比如别写“结果”，直接写“流式输出让首 token 延迟砍半”——读者不用点进去就知道发生了什么。
• 目录来一张
目录就像哈希表，一查就中；还能让人秒懂“这篇文章到底适不适合我”。
• 段落要瘦
三行五行最友好。关键句甚至可以独占一行，防止被埋没。
• 开头先给“剧透”
每段第一句就交代“这段在讲啥”，别让人追着你前文的尾巴跑。
例：
❌ “在此基础上，我们来看更快的办法。”
✅ “向量数据库能把嵌入搜索提速。”
• 关键词往前塞
把“主角”放到句首，扫一眼就能抓住核心。
例：
❌ “嵌入搜索可以通过向量数据库提速。”
✅ “向量数据库提速嵌入搜索。”
• 结论置顶
别玩“层层铺垫”的悬疑片，先把最有用的东西摆上来。
• 黑点 + 表格，多多益善
列表和表格天生就是扫读神器。
• 该加粗就加粗
重要信息别害羞，直接加粗，帮读者定位。
把句子写“顺”，而不是写“炫”烂句子就像减速带，每颠一下都让人想关页面。
• 能断就断
长句拆成两截，副词能砍就砍，废话一律下线。
• 别让人“二次解析”
例：
❌ “Title sections with sentences.”（读到 Title 时不知道是名词还是动词）
✅ “用句子写小节标题。”——一眼就能 parse。
• 少玩“左边挂树”
把重要信息先抛出来，别让读者在记忆里压栈。
例：
❌ “你需要面粉、鸡蛋、牛奶、黄油和一点盐来做煎饼。”
✅ “做煎饼需要面粉、鸡蛋、牛奶、黄油和一点盐。”
• “这个”“那个”能省就省
跨句的“this”最害人。直接点名上文的主题，或干脆删掉。
• 一致性强迫症
大小写、标点、命名风格……全部统一。别让读者在心里“咦？”
• 别替读者脑补
别说“你现在一定想知道……”，万一人家不想，就很尴尬。
换成中性说法：“要调用函数，只需……”
把门槛再降低一点点来的可能是资深程序员，也可能是第一天写 Python 的新手；可能是英语母语者，也可能靠翻译器硬啃。文档要“向下兼容”。
• 说人话
比你以为的再简单一点，但别弱智化。
• 缩写先写全
第一次出现写“检索增强生成（Retrieval-Augmented Generation，RAG）”，后面再用缩写。专家无感，新手救命。
• 把坑先填上
哪怕 95% 的人都会装 Python 包，也把命令贴出来。专家可以秒滑过，小白不会卡关。
• 术语要精准且亲民
能叫“输入”就别叫“提示”；能叫“最大 token 上限”就别叫“上下文限制”。
• 代码示例能 copy 就跑
尽量零依赖、零跳转，一页内自给自足。
• 先写高频问题
“怎么数 token”比“怎么优化 emoji 数据库”值钱 100 倍。
• 别教坏习惯
明知 API key 不能写代码里，示例里就千万别写。
• 先给大画面，再钻细节
讲推荐系统前，先一句“从 YouTube 到淘宝，推荐无处不在”，让读者心里有底。
规则是用来打破的上面所有技巧，都服务于一个终极目标：站在读者角度，替他们省时间、省脑力。
只要你能共情，就大胆打破任何规则——做当下最有利于读者的决定，就是好文档。