Tech alignment with ADRs, Working Groups and Narratives

Tech alignment with ADRs, Working Groups and Narratives

~ 4 minutes read featured in level up issue #43

Why align?

An aligned tech stack is key to drive tech initiatives like introducing new programming languages or changing communication protocols.

These approaches help me to drive tech alignment

Architecture Decision Records (ADR)

ADRs are text files describing why a software architecture decision are taken. There are 2 styles ADRs are authored:

  1. Context – concern – decision – quality – downside
  2. Problem – background/context – options – proposed solution – faq

Context – concern – decision – quality – downside

This ADR style references a user story or requirement as context to describe a concern. Based on these points, a technical/architectural decision is described to achieve quality as well as accepting downsides.

Problem – background/context – options – proposed solution – faq

This ADR style starts with a short problem description. A background/context part helps to understand the environment the problem exists. The following options part lists approaches that solve the problem or improve the problematic situation. The best option is selected as proposed solution. A closing FAQ section finalizes this ADR style.

Architecture Decision Records [1, 2, 3, 4] especially in its manifestation as MADR [5] are great to align on tech topics because these fit into the software engineers flow. This is because ADRs can be part of pull requests [6]. Pull requests are the canonical way of merging new code features into main branches. 87+ million GitHub pull requests are merged in 2018 according to octoverse numbers [7]. This indicates that the vast majority of software engineers work with pull requests. At the same time the concept of pull requests is controversial [8].

With ADRs part of pull request, not only the code change is aligned, but also the bigger context described in an ADR. This applies to all pull request flows [9].

Working groups

A working group [10] is formed when engineers come together and work on a specific goal. Almost all working groups I experienced or initiated were about to exchange software technical experiences and conclude from those. I observed these phases within the lifetime of a engineering working groups:

  1. Working group scope definition / goal setting
  2. Subject discovery phase
  3. Approach gathering
  4. Conclusion
  5. Documentation

All the points above are about alignment, however in particular conclusion is about alignment. Documenting the conclusion is key – without written documentation there is a high chance conclusions are understood differently amongst working group members and in extreme cases cause misalignment.


Narratives are text documents similar to ADRs, however the structure is different:

Narrative Title

  • Problem Statement
  • Context and/or Background
  • Solution Approaches
  • Proposed Solution/Conclusion
  • FAQ
  • Decision Record

The problem statement is the first section of such a narrative document. It is about pinpointing the issue. 5 sentences max is a good guideline to create a crisp problem statement. This is important to allow readers to decide: is this a topic I am concerned about? In case the problem statement is bigger, it’s recommended to split up in multiple problem statements within multiple narratives.
Since the problem statement is short the following Context and/or Background section can provide more details about the situation at hand.

3 solution approaches how to solve the problem is ideal to list in the Solution Approaches section. Almost all readers are able to have 3 solutions in mind, weigh up and decide for their favorites.

The authors’ favorite is described in the Proposed Solution/Conclusion section. This section describes why this is the proposed solution.

In case the authors envision questions readers may have, list these in FAQ section.

The decision record is a table to persist readers votes: 👍 – 👎

According to [11] those have been introduced to replace slide decks. Narratives focus on

  • collaboration about a problem statement at hand and solution approaches
  • documentation, not only about decisions potentially derived from solution approaches, but also about the ideation and discussion in the document that led to solution approaches

Key is to collaborate in order to create alignment, regardless of which approach you use to create tech alignment.


Be the first to comment

Leave a Reply

Your email address will not be published.


This site uses Akismet to reduce spam. Learn how your comment data is processed.