为具体名词：“基于消息格式，让我们讨论函数调用”优于“基于此讨论”。
· 保持一致性：统一标题大小写、标点（如尾随逗号）和命名规范（如 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 地址：
https://github.com/openai/openai-cookbook/blob/main/articles/what_makes_documentation_good.md
@jiaohusheji
· 保持一致性：统一标题大小写、标点（如尾随逗号）和命名规范（如 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 地址：
https://github.com/openai/openai-cookbook/blob/main/articles/what_makes_documentation_good.md
@jiaohusheji