#简洁明了

15小时前

优秀文档的核心原则 —— 来自 OpenAI 团队 Cookbook 文档的核心目标是将有用信息高效注入读者的头脑中，避免读者在信息海洋中迷失。优秀文档不是长篇大论，而是通过结构化、清晰和共情的设计，帮助读者快速解决问题。 1. 让文档易于浏览（Make docs easy to skim）读者很少从头到尾线性阅读文档，他们更倾向于跳跃式浏览，寻找直接解决问题的部分。因此，文档应像一张高效的“信息地图”，降低搜索成本，提高成功率。 · 使用描述性标题：标题应是信息完整的句子，而非抽象名词。例如，用“流式处理将首 token 响应时间缩短50%”代替“结果”，让读者无需深入阅读即可获知要点。 · 添加目录：目录如哈希表般加速定位，同时提供文档整体线索，帮助读者判断是否值得阅读。 · 保持段落简短：短段落易于扫描；关键点可独立成一句单句段落，避免被长文淹没。 · 以独立主题句开头：段落和节的首句应自成一体，不依赖前文。例如，“向量数据库可加速嵌入搜索”优于“基于此，让我们讨论更快的方法”，便于跳读者快速理解。 · 主题词置于句首：如“向量数据库加速嵌入搜索”比“嵌入搜索可由向量数据库加速”更高效，因为读者只需读前两词即可把握主题。 · 要点前置：将最重要的信息置于文档或节的顶部，避免司马式渐进式展开，先结果后过程。 · 多用 bullet 列表和表格：这些格式天然支持扫描，提高可读性。 · 加粗关键文本：大胆突出重要内容，帮助读者快速锁定。这些技巧的核心是“读者优先”：设计时假设读者时间有限、注意力分散。 2. 写出高质量文本（Write well）糟糕的文风会消耗读者的认知资源，导致疲劳。优秀文档应追求简洁、流畅，减少解析负担。 · 句子简洁：拆分长句、去除副词和冗余词，使用祈使语气（如写作书籍建议）。 · 确保无歧义解析：避免词性模糊的句子。例如，“用句子标题节”（Title sections with sentences）易混淆词性；改为“将节标题写成句子”（Write section titles as sentences）更易解析，即使稍长。 · 避免左分支句子：这类句子要求读者短期记忆过多，如“你需要面粉、鸡蛋、牛奶、黄油和少许盐来做煎饼”。改为右分支：“做煎饼需要面粉、鸡蛋、牛奶、黄油和少许盐”，更符合大脑处理习惯（类似于深度优先搜索）。 · 少用指示代词：如“this”跨句使用易造成回溯负担。改为具体名词：“基于消息格式，让我们讨论函数调用”优于“基于此讨论”。 · 保持一致性：统一标题大小写、标点（如尾随逗号）和命名规范（如 Cookbook 中的下划线+句首小写），避免读者分心。 · 不假设读者心态：避免“你现在可能想了解函数调用”这类推测；改为“To call a function, ...”，保持中立。写作原则源于认知科学：减少大脑负载，让内容自然流动。 3. 广泛有益于读者（Be broadly helpful）文档用户背景多样（从新手到专家、多语言使用者），优秀文档应包容性强，覆盖潜在痛点，而非仅针对“理想读者”。 · 用简单语言：比预期更简化解释（但不低估）。考虑非母语者和术语生疏者，优先清晰而非炫技。 · 避免缩写：全写出，如“instruction following”而非“IF”；“retrieval-augmented generation”（或“搜索-询问流程”）而非 “RAG”。专家成本低，新手收益高。 · 预解常见问题：即使 95% 读者知晓 Python 包安装，也值得说明——专家可略过，新手避免卡壳。记住，跨语言专家（如 JavaScript 开发者）可能 Python 是新手。 · 选用具体准确术语：避开行话，如用 “input” 代替 “prompt”，“max token limit” 代替 “context limit”，更自明且贴合实际。 · 代码示例通用自洽：最小化依赖，避免额外库或跨页引用，确保可直接复制运行。 · 优先高价值主题：聚焦常见问题（如 token 计数），而非罕见场景（如表情符号数据库优化）。 · 避免不良习惯：如 API 密钥勿硬编码示例。 · 以广义开场引入主题：如解释推荐系统时，先提及 YouTube、Amazon 等应用场景，增强读者安全感。这些建议体现共情：文档是为“所有人”服务的工具，过多假设会疏离部分用户。 4. 必要时打破规则（Break these rules when you have a good reason）这些是指导而非铁律。文档写作是移情练习：代入读者视角，选择最有帮助的方式。最终，灵活应用才能适应具体情境。 OpenAI Cookbook 地址：

#文档写作 #OpenAI Cookbook #高质量文档 #用户体验 #简洁明了

5个月前

一针见血！

#精准洞察 #见解深刻 #简洁明了