编写架构文档的最佳实践 - Singh

21-11-12 banq

一个有据可查的架构可能是成功与失败项目之间的区别。它带来了巨大的收益,并确保系统易于理解、设计得周到,并且可以与他人交流。在您记录的内容中务实,使其成为流程的一部分,并在您的架构、设计和解决方案中不断深思熟虑,以满足您的业务需求。

  • 记录重要的事情和重要的时间。并不是所有的事情都需要在一开始就记录下来。架构和相应的设计可能是流动的,尤其是在测试新功能、处于试点模式或构建新系统时。有些可能是暂时的,而有些则需要是永久性的,所以从工作代码开始,所需的最小集,并随着时间的推移而扩展。
  • 从一开始就捕获所有架构决策。有机架构不是架构。架构是深思熟虑的、突发的和有意的,避免了我们质疑为什么系统及其组件以某种方式设计的情况,并保持对导致特定方法的力量的明确性。记录决策将使您能够回顾并验证解决方案是否继续满足业务需求,并在扩展或重构它们时提供帮助。
  • 跟踪架构债务以保持对需要解决的问题的当前管理良好的记录,并促进产品级别的规划和待办事项梳理。必须不惜一切代价避免无证债务。
  • 将文档架构作为流程的一部分,而不是作为追赶活动或在有时间时,因为永远没有时间。将“设计完成”定义为完成架构、其设计和所需的工件。正如未经测试的代码会引入业务风险一样,未记录的架构也会带来业务风险。
  • 最大化工件的自动化。虽然有些工件需要手动工作,但完全有可能自动创建其他工件,包括上下文和界面图、流程流、服务和 API 目录以及基础架构图。利用自记录技术和自动化,可以根据构建的内容和正在运行的内容保持工件的最新状态。

 

1
猜你喜欢