极客大学架构师训练营第一周李智慧老师主要讲了架构师、架构方法、架构文档方面的内容。结合自己的工作经历，对架构文档方面的还是有一些感触的。从CMMI在公司盛行时的重文档阶段、敏捷开发盛行的“无”文档阶段，到现在的轻文档阶段，每个阶段都有它的优缺点，并且随着技术/业务的演化而最终演化到现在状态。
重文档阶段
十多年前，CMMI还统治公司软件开发。那时候大家做桌面程序开发，学瀑布模型、面向对象分析与设计、UML、设计模式等等；写完备规范的文档，从需求分析说明书、概要设计文档到详细设计文档，都详尽撰写供专家评审。请来的培训师（在波音做过软件开发的）在OOAD课上甚至宣称，软件开发的时间分配应该是 分析：设计：写代码 = 7：2：1，（几乎）所有细节、问题都应在分析设计阶段发现并解决。当然这也只是一家之言，或许在特定领域（给飞机写软件）需要这样，毕竟一个bug或许就会引起飞机故障甚至生命丢失。
在这个阶段，作为一个新人是很幸福的。你可以看公司大佬们写的各种文档，学习他们的设计思路、设计风格；可以学习并且实践最严格的面向对象分析与设计，UML各种图的标准画法；在接手项目时总有文档帮助你快速你理解现有的代码和功能。但与此同时，你也会发现很多详细设计文档和代码有出入、不一致。当你开始写代码就能体会到这种不一致是如何产生的：没人愿意改了代码后再去检查设计文档并更新，尤其当文档最初并不是你写的。
当然作为一个老人，也会体会到各种类似的幸福和烦恼。你可以有更多时间花在设计文档上，有更多时间参与其他项目的设计评审，学习其他人的设计、了解其他项目的架构。但同时文档细节内容也会占据你大部分时间，到后期还很难维护文档和代码的一致性。
在重文档阶段，架构师用文档与业务人员和管理层沟通还是比较有效的。但是在开发团队内部，文档的作用不大，甚至还有些鸡肋，像那个总是（一直）处于“过时”状态的详细设计文档。
“无”文档阶段
在11-12年时，敏捷开发开始在公司被使用。初期采用一些极限编程的实践，所以开发团队集体创作设计文档。开发人员集体讨论并在白板上画各种类图、时序图，然后就是写代码，好像都不太需要架构师的感觉。后来架构师找到了一个发挥作用的地方，就是把需求转化成设计，做顶层的概要设计。然后开发团队在设计好的模块内部做设计编码，毕竟团队达不到极限编程的前提假设即所有成员都是多面手、啥都能干。
在这个阶段，标准正式的架构文档很少，甚至有些文档直接是把白板图的照片做内容。一时间，重直接交流而轻文档的思想发展的过了头，大家都直接交流而不留下任何文档。新人找不到任何参考文档，直接看代码多走一些冤枉路。老人则更关注各种敏捷思想技能的积累，而把项目相关的知识、架构、设计等等都变成经验放脑袋里，而没有输出到文档里。
在“无”文档阶段，架构师和开发团队内部交流直接有效，对细节把控和了解也更多，但是容易变成知识瓶颈。和业务人员沟通就变成了周期性的报告和演示，这样倒是可以很快获得各种反馈，不断优化调整需求。
轻文档阶段
最近几年，公司的主要系统都开始上云，从桌面系统直接跳到云原生和微服务。这个巨大的跃迁对所有的管理、业务、开发人员都形成了挑战，只靠白板上的各种UML图已经很难，大家需要一些更正式文档去辅助理解、学习。所以这时架构文档的需求又回来了。逻辑视图和部署图可以更好的帮助业务人员理解系统如何达到业务目标，系统又是如何部署执行、对最终用户有什么影响，还有一些不那么标准的微服务级别上的交互图、数据流图帮助开发人员理解整体的系统流程和功能等等。基于这些需求，架构师又开始重新重视架构文档，在项目中提供更多的文档。
这个阶段与重文档阶段所不同的是，这个阶段的文档更多是“活”的，它随着系统的变化而不断变化。在敏捷开发的大环境下，架构文档会不断地被拿出来与业务人员、管理人员、开发人员讨论使用，在这些讨论地过程中文档又会被不断地更新。在不断地更新的过程中，一些容易变的、具体实现相关的细节就被删掉了，留在文档中的更多是那些基础的、不易变的技术方案选择、架构决定等等。
总结
从重文档到轻文档，都是由于技术的发展、开发方式的变化而变化的。每种模式都是适应当时情况的选择，当然也没有那种是十全十美的。架构师做的很多事情就是trade-off, 在架构文档上也不例外，需要根据项目实际情况来决定写多少文档，写什么样的文档。架构文档也和公司行业性质、主要业务有关，像我所处的公司属于传统能源行业，这或许也会造成文中所说的情况与软件互联网行业有所不同。所以，架构文档没有统一的标准，只有合适的。