《程序员必读软件架构 Part5 为软件生成文档》

概述

代码能说明一些问题，但不会讲述所有的故事，很多事情通过代码无法说清楚，或者从代码了解会比较费功夫，例如

• 软件系统如何融入已有的系统形态
• 为什么会选择正在使用的技术
• 软件系统的整体结构
• 各个组件在运行时部署在哪里，如何相互沟通
• Web层如何知道在哪里找到中间层
• 日志/配置/错误的处理/其他采用了什么方法，在代码库中是否一致
• 代码库中是否使用了通用的模式和原则
• 栈的安全性是如何实现的
• 如何实现可伸缩性
• 与其他系统的接口如何工作
• 其他

敏捷宣言宣称可以工作的软件重于面面俱到的文档，但是这并不是不写文档的接口，一个良好的文档可以帮助别人快速的了解系统的各个方面，在这方面其实是降低了沟通成本的

包含内容

语境

可以用语境图来表示，可以参考这篇文章

功能性概览

意图

结构

动机

受众

质量属性（非功能性需求）

意图

结构

动机

受众

约束

意图

结构

动机

受众

原则

意图

结构

动机

受众

软件架构

容器图和组件图，可参考这篇文章

外部接口

意图

结构

动机

受众

代码

意图

结构

动机

受众

数据

意图

结构

动机

受众

基础设施架构

意图

结构

动机

受众

部署

意图

结构

动机

受众

运营和支持

意图

结构

动机

受众

决策日志

意图

结构

动机

受众