---
title: "怎样才算好文档"
description: "优秀文档的核心原则 —— 来自 OpenAI 团队 Cookbook写文档是一种同理心的体现文档的核心目标是将"
date: 2025-10-26T03:08:25Z
canonical: https://xiaobox.github.io/p/2025-10-26-yang-cai-suan-hao-wen-dang/
author: 小盒子
categories: ["AI"]
tags: ["Python", "JavaScript", "RAG", "Prompt", "Embedding"]
source: https://mp.weixin.qq.com/s/vBuo8EjXk_RLIWhJjBwgRQ
license: CC BY-NC-SA 4.0
license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/
---

# 怎样才算好文档

> 优秀文档的核心原则 —— 来自 OpenAI 团队 Cookbook

# 写文档是一种同理心的体现

文档的核心目标是将有用信息高效注入读者的头脑中，避免读者在信息海洋中迷失。优秀文档不是长篇大论，而是通过结构化、清晰和共情的设计，帮助读者快速解决问题。

# 让文档易于浏览

> 读者很少从头到尾线性阅读文档，他们更倾向于跳跃式浏览，寻找直接解决问题的部分。因此，文档应像一张高效的 “信息地图”，降低搜索成本，提高成功率。

●**使用描述性标题**：标题应是信息完整的句子，而非抽象名词。例如，用 “流式处理将首 token 响应时间缩短 50%” 代替 “结果”，让读者无需深入阅读即可获知要点。

●**添加目录**：目录如哈希表般加速定位，同时提供文档整体线索，帮助读者判断是否值得阅读。

●**保持段落简短**：短段落易于扫描；关键点可独立成一句单句段落，避免被长文淹没。

●**以独立主题句开头**：段落和节的首句应自成一体，不依赖前文。例如，“向量数据库可加速嵌入搜索” 优于 “基于此，让我们讨论更快的方法”，便于跳读者快速理解。

●**主题词置于句首**：如 “向量数据库加速嵌入搜索” 比 “嵌入搜索可由向量数据库加速” 更高效，因为读者只需读前两词即可把握主题。

●**要点前置**：将最重要的信息置于文档或节的顶部，避免司马式渐进式展开，先结果后过程。

●**多用 bullet 列表和表格**：这些格式天然支持扫描，提高可读性。

●**加粗关键文本**：大胆突出重要内容，帮助读者快速锁定。

这些技巧的核心是“**读者优先”：设计时假设读者时间有限、注意力分散。**

# 2. 写出高质量文本

> 糟糕的文风会消耗读者的认知资源，导致疲劳。优秀文档应追求简洁、流畅，减少解析负担。

●**句子简洁**：拆分长句、去除副词和冗余词，使用祈使语气（如写作书籍建议）。

●**确保无歧义解析**：避免词性模糊的句子。例如，“用句子标题节”（Title sections with sentences）易混淆词性；改为 “将节标题写成句子”（Write section titles as sentences）更易解析，即使稍长。

●**避免左分支句子**：这类句子要求读者短期记忆过多，如 “你需要面粉、鸡蛋、牛奶、黄油和少许盐来做煎饼”。改为右分支：“做煎饼需要面粉、鸡蛋、牛奶、黄油和少许盐”，更符合大脑处理习惯（类似于深度优先搜索）。

●**少用指示代词**：如 “this” 跨句使用易造成回溯负担。改为具体名词：“基于消息格式，让我们讨论函数调用” 优于 “基于此讨论”。

●**保持一致性**：统一标题大小写、标点（如尾随逗号）和命名规范（如 Cookbook 中的下划线 + 句首小写），避免读者分心。

●**不假设读者心态**：避免 “你现在可能想了解函数调用” 这类推测；改为 “To call a function, ...”，保持中立。

**写作原则源于认知科学：减少大脑负载，让内容自然流动。**

# 3. 广泛有益于读者

> 文档用户背景多样（从新手到专家、多语言使用者），优秀文档应包容性强，覆盖潜在痛点，而非仅针对 “理想读者”。

●**用简单语言**：比预期更简化解释（但不低估）。考虑非母语者和术语生疏者，优先清晰而非炫技。

●**避免缩写**：全写出，如 “instruction following” 而非 “IF”；“retrieval-augmented generation”（或 “搜索 - 询问流程”）而非 “RAG”。专家成本低，新手收益高。

●**预解常见问题**：即使 95% 读者知晓 Python 包安装，也值得说明 —— 专家可略过，新手避免卡壳。记住，跨语言专家（如 JavaScript 开发者）可能 Python 是新手。

●**选用具体准确术语**：避开行话，如用 “input” 代替 “prompt”，“max token limit” 代替 “context limit”，更自明且贴合实际。

●**代码示例通用自洽**：最小化依赖，避免额外库或跨页引用，确保可直接复制运行。

●**优先高价值主题**：聚焦常见问题（如 token 计数），而非罕见场景（如表情符号数据库优化）。

●**避免不良习惯**：如 API 密钥勿硬编码示例。

●**以广义开场引入主题**：如解释推荐系统时，先提及 YouTube、Amazon 等应用场景，增强读者安全感。

**这些建议体现共情：文档是为 “所有人” 服务的工具，过多假设会疏离部分用户。**

# 4. 必要时打破规则

**这些是指导而非铁律。文档写作是移情练习：代入读者视角，选择最有帮助的方式。最终，灵活应用才能适应具体情境。**