敏捷软件开发宣言 1 说“ 可以工作的软件重于面面俱到的文档”，看到很多软件团队将其解释成“不写任何文档”真是令人难以置信。其中的基本原理是，对最终用户来说真正工作的软件比一堆面面俱到的文档有价值得多，但是很多团队把敏捷宣言中的这句话当成了完全不写任何文档的借口。很遗憾，代码不会讲述完整的故事 ，缺少关于复杂软件系统的辅助信息源会让团队在努力浏览代码时被拖累。
1 http://agilemanifesto.org
我也坚信，软件团队有义务和代码库一起交付一些辅助文档，特别是那些在外包或离岸合同下构建软件的团队。我见过IT咨询组织交付高度复杂的软件系统给客户时甚至没有一页支持文档，往往是因为团队就没有任何文档。如果原来的软件开发者离开了咨询组织，新的团队能否理解软件的方方面面，它如何构建以及如何以契合原始架构的方式增强？那可怜的客户怎么办？是不是应该只 交付给他们可工作的代码库？
问题是，当软件团队考虑文档时，他们通常想到的是基于一个1990年代软件架构文档模板的庞大微软Word文档，其中还包括一个需要为他们的软件支持的每一个用例绘制统一建模语言（UML）类图的部分。几乎没有人喜欢阅读这种类型的文档，更别说写了！我们需要一种不同的方法。我们应该考虑把辅助文档作为一个不断变化的旅游指南，而不是一个综合的静态历史片断。但这样的指南应该写些什么？