Architecture Design Reviews and Architecture Decision Records

While reading George Fairbanks` excellent book: Just Enough Software Architecture I came to section 15.6.2 Informal analysis techniques and then started to research one of them: Architecture Design Reviews.

What does Architecture Design Review gives

I find several benefits of this informal technique that will bring value to big and small companies alike for the following reasons:

  • It makes you fix your own mistakes in the earliest responsible moment because it forces you to read and rethink more carefully your own architectural design decision before you send it for review. Therefore it improves the quality in all the different aspects
  • It is an exercise in documenting architecture
  • It demands more respect from you for the time and effort that your teammates will spend reviewing
  • It forces upon you the Thought Distillation Discipline much like TDD forces you to think about your interface contracts. Think of it like code review for architecture
  • It protects you from reinventing an already known solution or the wrong solution altogether because your reviewers will point this out to you or will help you find it
  • It facilitates knowledge sharing between architects and developers and distils some standards and good practices along the way
  • It provides a structured approach to create and log architecture design decisions which makes the life of your fellow developers and architects much easier and provides value to your clients and your company

The value an Architecture Design Review gives is more than the time it takes.

How to begin with Architecture Design Review

The path that I follow:

  • Add the client spec in your project wiki for anybody to read.
  • Distil non-functional requirements
  • Distil functional requirements
  • Create an architecture epic
  • Create PBI/Issue for each Architecture Decision Record – they are logically separate and have separate reasons to change or to be superseded
  • Create a folder and an .md file for (each) the Architecture Decision Record in the project wiki with the following tool – https://github.com/npryce/adr-tools – or by hand or by another tool.
  • Create a markdown file with the [following](architecture-decision-record/index.md at main · joelparkerhenderson/architecture-decision-record · GitHub) structure for the Architecture Decision Record and add these two more
    • Metadata – Who is the author, When is it approved, Who approved it, Who reviewed it
    • Compliance Guard rails – What keeps us from going astray? An automated script or manual check list.
  • Create a task for the Architecture Design Review to initiate the discussion
  • The reviewers should use the PBI/Issue comments for the discussion
  • The Architecture Decision Record author should reflect the notes and the final status in the markdown file and be done with it

Books, articles, posts and videos I used to distil the content of this post

I can only say “Thank you!” to George Fairbanks, Michael Nygard, Christos Gkoros and Joel Parker Henderson for the sharing of their knowledge thus improving the field.