Documentation Best Practices

## 《Documentation Best Practices》摘要 《Documentation Best Practices》文档从代码健康的角度出发，提出了编写和维护技术文档的最佳实践，强调文档的简洁性、及时性和可维护性。以下是核心内容的总结： ### 1. 最小可行文档 倡导保持文档简短且实用，避免冗长和零散。建议开发人员： - 识别真正需要的文档（如发布文档、API文档、测试指南等）。 - 定期删除无用的内容，每次少量删除。 - 保持文档如同盆栽树般（bonsai tree）经常修剪，活力十足。 ### 2. 与代码同步更新文档 建议在代码变更的同时更新文档，以确保文档的准确性和一致性： - 每次代码提交（CL, Change List）都要更新相关文档。 - 评审人员应仔细检查文档是否同步更新，包括docstring、README.md等。 ### 3. 删除过时文档 过时的文档会导致误解和效率低下： - 从确定无误的错误内容开始删除，先处理清晰的部分。 - 整个团队参与评估文档，快速决定保留或删除。 - 迁移时默认选择删除，而不是保留。 - 改进是循序渐进的过程。 ### 4. 文档是代码的故事 文档承担着代码的“讲故事者”角色： - 内联注释应解释代码存在的原因。 - 方法和类注释：详细说明方法的功能、使用方法、限制、返回值和异常等信息。 - 类/模块注释（如Javadoc/docstring）概述类的功能和使用示例，优先列出最简单的用例。 - README.md应帮助新手快速了解目录的目的、主要文件、维护者和进一步学习资源。 - 文档是开发过程中的重要组成部分，工程师应以清晰、实用的方式书写，优先满足人可读性，而非仅仅是计算机可读性。 文档质量不是一蹴而就的，而是通过团队的持续努力逐步完善。通过保持文档的“活力”，及时更新和定期清理，可以让文档真正成为代码的有力补充，提升工程师的工作效率和代码的可维护性。