雷达哔哔哔 - #1-Lightweight Architecture Decision Records

1. 推荐度:

TRIAL[ 2016.11 | 2017.03 ] -> ADOPT[ 2017.11 | 2018.05 ]

2. 所属象限:

Techniques

3. 关注问题:

  • 传统的重文档编写维护量大,随着业务发展,很难保持同步
  • 在一些敏捷项目中,随着关键文档的确实,项目Knowledge及决策丢失导致长生命周期的项目知识传递问题。

4. 解读:

项目要不要写文档一直是一个很有争议的问题。在过去,项目一般都要写众多的文档,什么需求说明书,概要设计,详细设计,数据库设计,balabala设计……而这些文档的作用往往只是为了【过评审】或是【招投标】,写文档的形式也更多是简单的复制粘贴。

项目拿下了,过审了,一旦开动起来,文档反而就被束之高阁,再也无人过问了。

所以就有很多人没日没夜地写着千篇一律的文档、文档、文档……

终于有一天,盼来了敏捷,并看到了敏捷宣言中硕大的一句:


敏捷宣言

唉呀妈呀,终于见到了亲人,从此高举着敏捷的大旗,与文档势不两立。

再有人一旦敢提起写文档,就把早已准备好的“敏捷大棒”从身后掏出来,劈头就是一棒槌……

不得不说,敏捷又一次背了口黑锅,敏捷宣言所推崇的并不是简单的不写文档,而是认为之前那种写文档的方式根本没有体现出其应有的价值。还不如代码写的漂亮些,测试写的完备些,让代码和测试成为真正有价值的文档。

而这,相对于简单的复制粘贴攒文档,对于团队的要求反而更高了。

世间万物,物极必反。

就算好的敏捷团队中,随着时间的积累,我们也同样发现了知识也在不断的流失。虽然有着完备的测试,和易读的代码,但这些毕竟过于细节,无法快速还原当时设计或重构时的所有上下文。

所以在技术雷达中推荐使用“ Lightweight Architecture Decision Records”来记录项目重要决策,相比于传统文档,他最大的特点就是轻量(Lightweight),关注于创造价值而不是遵循流程。

让我们看个ADR的模板:

ADR Template

同时技术雷达也建议我们并不要将ADR束之高阁,放到Wiki或是文档库中。而是随着代码放到Git或其他版本控制工具里,这样既可以保持最大程度与代码同步,又能跟踪Decision的变更历史。

推荐的Adr-Tools工具,可以帮助我们容易的做到这些。

5. 工具:

GitHub - npryce/adr-tools: Command-line tools for working with Architecture Decision Records

6. 延展阅读:

  • Lightweight Architecture Decision Records | Technology Radar | ThoughtWorks
  • Blog | Documenting Architecture Decisions | Relevance
  • GitHub - joelparkerhenderson/architecture_decision_record: Architecture decision record (ADR) examples for software planning, IT leadership, and template documenation
  • Documenting Architectural Decisions Within Our Repositories — Embedded Artistry
  • Architectural Decision Records | adr.github.io
  • What are lightweight Architecture Decision Records?

你可能感兴趣的:(雷达哔哔哔 - #1-Lightweight Architecture Decision Records)