知识卡片

普通读书笔记卡 · 1826.a.1

架构文档少而充分

理解等级:初级

为什么写架构文档:主要目的是让架构能被沟通——不同利益相关者(甚至彼此未曾谋面的开发者与维护者)之间的有效沟通;为详细设计、培训材料等提供追溯上下文;传达备选方案及其利弊;帮助规划从现有架构到新架构的迁移;通过元素及其依赖帮助制定实现顺序、理解调整影响;提醒架构师自己决策背后的原理;识别可重用资源;支持评估实现是否符合规格。

四个步骤: 1. 识别利益相关者组——首先了解目标对象,按共同关注点分组(如开发人员组、用户组); 2. 选择视点——让各组的关注点得以表达,视点规定需要哪些工作产品(功能视点要求功能模型,部署视点要求部署模型); 3. 创建工作产品——向模型添加元素和图表; 4. 给架构描述打包——不是把所有工作产品直接丢给利益相关者(他们未必能用建模工具),而是打包成更易使用的软件架构文档,按视图组织。

最优方法:尽可能少但要充分:对应敏捷宣言“可用的软件胜于详尽的文档”。按利益相关者的需要决定要表达什么;如果利益相关者是团队成员或维护人员,还要注意维护——保证在适当的地方保持最新且相互一致。

这张卡片看不懂?

已有反馈 · 0 / 10 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    参考来源

    - 位置:《架构实战:软件架构设计的过程》第04章《第4章 编写软件架构文档》第4章导语;4.1 最终的结局(最优方法:编写的文档要尽可能少但要充分)(源文件:extracted/架构实战软件架构设计的过程/_epub-src/OEBPS/text00000.html,来源项目 book-sources) - 结论依据:第4章导语列出编写软件架构文档的八项好处;4.1节给出识别利益相关者组、选择视点、创建工作产品、打包架构描述四个步骤,并以最优方法“编写的文档要尽可能少但要充分”说明按利益相关者需要决定文档范围并保持更新一致。 - 原始内容:敏捷的原则之一是“注重可用的软件,胜于详尽的文档”(敏捷宣言),这个原则提醒您:创建的工作产品应该尽可能少,但要充分。