架构师的沟通与文档实践指南

# 架构师的沟通与文档实践指南 ## 1. 结构化沟通助力项目推进 架构师确保项目顺利进行的主要方式之一是通过结构化沟通，这往往意味着需要组织会议。为使会议富有成效，拥有一套核心文档供定期审查和签字确认是个不错的方法。与项目领导层合作，将此过程设定为强制性的正式项目流程。通常还需要开展协作工作会议来处理这些文档。 建立定期的架构审查委员会（ARB）会议有助于保持清晰的沟通渠道和维护项目文档。鼓励领导层定期参与，以确保他们重视这些会议。同时，邀请具有深入见解的架构师和工程师参加。若有安全或数据架构团队，他们也是很好的合作伙伴。 ARB 会议的主要焦点应围绕做出决策、记录决策并进行沟通，这些决策需与项目的长期和短期成功指标保持一致。确定决策的详细程度更像是一门艺术而非科学。决策可以由 ARB 做出，也可由团队独立做出，或者团队做出后提交给 ARB 审查。记录和分享无需升级的决策，能为项目的发展路径提供指引，在涉及多个团队时，这一点尤为关键。 以下情况的决策通常需要提交给 ARB 审查： - 导致技术方法与原计划有重大改变，例如： - 新的集成 - 权限结构的变更 - 购买第三方组件 - 创建可复用组件 - 导致项目直接成本或后续维护成本发生变化。 - 产生可能在后期造成影响的技术债务。 - 标志着项目的重要里程碑。 - 为避免事后诸葛亮式的质疑和利益相关者的缺席提供保障。 - 不会让领导层感到乏味。 一个维护良好的决策日志能为项目的技术组件提供重要记录。一般而言，一个团队每个冲刺应产生 1 - 5 个可记录的决策。 ## 2. 文档：架构师的重要沟通资产 文档是架构从业者的另一项重要沟通资产。尽管优先处理文档工作可能会面临诸多即时事务的挑战，但这应被视为架构师的主要成功衡量标准。成功的架构文档实践关键在于制定一个周全的计划，并通过流程确保定期更新和沟通关键变更。前文提到的 ARB 会议和决策文档应融入文档实践中。安排审查会议（可独自或与利益相关者一起），为文档更新设定节奏，并为自己设定完成任务的时间。 务必为文档添加时间戳，始终假定当前正在处理的文档是他人能找到的唯一且最佳文档。尽可能提供当前情况的背景信息，这有助于读者理解后续发生的事情。描述导致文档中状态与上一版本不同的事件。 ## 3. 选择记录和绘制的内容 架构师工作中更具艺术性的部分在于选择记录和绘制的内容。由于保持文档更新需要投入精力，因此决定将时间和精力投入到哪些方面至关重要。如前文所述，使遵循和参与文档实践成为流程的强制性部分是至关重要的。与领导层和项目经理合作，明确对正式项目文档的期望。建立参与的节奏和评分系统。以下是一些典型的图表层级及其绘制的驱动因素： ### 3.1 城市视图 在处理文档方面有几种常见的思路。我倾向于使用 4 + 1 架构视图模型作为项目文档工作的核心。首先从宏观层面创建项目的“城市视图”，从多个角度审视项目。这个顶级的全面视图至关重要，因为它可以作为其他所有文档的可视化“目录”。要确保投入足够的时间来更新这个顶级视图，否则架构师规划的路径将无法被他人理解。 ### 3.2 应对复杂性 一旦出现复杂性或混淆情况，应及时调整图表和文档。一些看似简单的术语，如“应用程序”，可能有多种含义。若不提前明确其定义，可能会导致关键利益相关者之间的协调出现问题。不能期望同事仅通过自学就能跟上你的理解进度。 要定期分享你的愿景，若发现混淆，及时解决。需牢记复杂性