Good Docs Describe, Bad Docs Prescribe
10 months ago
- #Documentation
- #Agile
- #Software Development
- 敏捷宣言优先考虑'可工作的软件胜过全面的文档'。
- 现代文档形式如架构决策记录（ADRs）、征求意见稿（RFCs）和校准文档可能演变成官僚主义障碍，拖慢进度并固化未经检验的假设。
- 优质文档应描述软件当前状态而非未来愿景，且需跟随实现过程以保持准确性。
- 自动生成的文档、内联代码注释、项目自述文件和文学化编程之所以有效，是因为它们与代码锚定，能避免信息脱节。
- 敏捷团队应优先保证软件可运行，并随代码演进调整文档，避免落入预设式文档的陷阱。