一篇好的文档，核心在于将有用信息准确传递给读者。优秀文档的关键在于易读、简明且具条理，能有效减少读者的搜索时间，提升解决问题的效率。
首先，文档要便于快速浏览。通过清晰的章节标题指引读者，优先使用带信息量的标题而非抽象名词，比如“Streaming减少首个token时间50%”比单纯写“结果”更直观。目录的设置能快速定位信息，也帮助读者判断文档是否值得深入阅读。段落保持简短，关键观点单独成段，避免信息埋没。段落开头用独立且主题明确的句子，方便读者快速捕捉内容。主题词尽量放在句首，提升扫描效率。重要结论应放在前面，避免冗长铺垫。使用项目符号和表格辅助梳理内容，重点文字可适当加粗，帮助突出关键点。
其次，写作风格要力求清晰简洁。避免复杂长句和多余修饰，倾向用简明句式表达，确保句子结构易于理解。避免左侧分支长句和指示代词“这”“那个”等跨句引用，减少读者记忆负担。保持一致性，无论是大小写、标点还是命名风格，都应统一，避免干扰阅读体验。避免揣测读者状态，使用客观陈述更专业。
此外，文档应对不同层次读者友好。语言简单明了，避免缩写，尽量写全称，方便非母语及初学者理解。主动提供潜在问题的解决方案，兼顾初学者和专家的需求。用准确且具体的术语替代行话，比如用“输入”替代“prompt”，“最大token限制”代替“上下文限制”。代码示例应尽量通用且独立，减少依赖，方便复制运行。优先覆盖常见问题，避免稀有细节占用过多篇幅。绝不示范坏习惯，比如代码中暴露API密钥。介绍新主题时，先用广泛背景铺垫，使读者更易接受和理解。
最后，文档写作是对读者的同理心体现，应灵活应用规则，针对读者需求做出最佳选择。
