Decision-Making, Simplified: Async LDRs (Part 2)

Overview

In the first part of this series, we explored the concept of Lightweight Architecture Decision Records, and their evolution into Async LDRs. We also uncovered the key dimensions of a decision that should be captured in a LDR.

Another crucial aspect of a decision record is its template. As you may know, a template means a pre-formatted file which makes it easier to create associated documents, and is often supported with tooling options. In our context, the more lightweight, accessible, and contextual the ADR Template is, the higher is the longevity of the associated ADRs. Also, ADR / LDR / Async LDR Templates are structurally equivalent, with the semantic differences being context (technology, process or people) or communication mode (sync or async or mixed).

Authoring a LDR

If your team is considering this technique, I would recommend starting with a meta decision: “Decision-making strategy for Team Awesome” (or equivalent). While this meta activity may sound trivial, I have found it to be very effective in driving consensus, uncovering team-specific nuances and establishing a foundation for future LDRs.

Paths and vehicles symbolizing choices and context

Beyond the decision dimensions outlined in my first post, here are additional best practices distilled from my experience:

• Easy authoring over sophisticated tooling – A simple text-based document in Google Drive (or a wiki) seen by the core and extended teams is likely to gain more traction, compared to a file with ".adr" extension in a GitHub repository generated by a plugin. Like with exceptions to any rule, the ".adr" file may be more applicable, if the bounded context of your decision records is within the purview of system design.
• Bias for action over formal process – Avoid turning the LDR approach into lengthy meetings or review cycles. Nor, should LDRs be treated as substitutes for whiteboard notes or casual conversations. The goal of LDRs is to provide an equal thinking space for folks, make trade-offs visible, and build consensus effectively.
• Maintainable linked records over snowflake one-off decisions – Everyone loves software with good (and updated) documentation, since it makes our lives so much easier. In a similar vein, LDRs should be treated as living artifacts of your system or team. Be aware that not every decision warrants a formal record, focus on those which have significant implications for your project or team.
• Collective commitment over hero culture – Encourage everyone on the team to participate actively in LDR discussions and contribute to decision-making. Facilitation (sync or async) plays a pivotal role here, which will be covered in my next post. Driving a LDR to closure is not one person’s job, the team has to commit collectively and explicitly. Do not assume silence or non-participation means alignment.

An ADR story

Let's talk about a real-world ADR experience from my journey.

Situation - In 2019, I played the Tech Delivery Lead role on a consulting engagement for a B2B travel provider. This involved migrating a complex monolith into microservices for scale and performance, and designing a set of interoperable, travel-industry compliant, and low-maintenance APIs. We were also working with different teams focused on architecture, development, testing and infrastructure.

Task - The existing monolith services were built with SOAP protocol and used XML data format, while the proposed microservices were expected to be RESTful APIs and use JSON data format. Further, the monolith was in .NET, while the microservices were being built in Java. As expected, interoperability became a critical architectural aspect.

Action - The architects group advised that external services need to adhere to a travel alliance specification, which was SOAP and XML based; this limited our choice for external services. However, the usage of JSON RESTful APIs for internal services seemed like the de-facto choice, especially SOAP XML microservices (implementation and tooling) are not popular. The decision considerations seem to be popular vs pragmatic, lower JSON payload size, more structured XML data model and cycle time for XML-JSON conversion. As mentioned above, we first agreed on using ADRs; and then leveraged an ADR to table this decision, consider our options, seek inputs, make a choice, commit as a group and document the approach.

Result - The primary areas for different groups seem to be technology governance (architects group), legacy code support (Dev SMEs), and engineering practices (consultants). The ADR approach provided a visible and open structure for different groups to add their perspectives, understand the available choices, and ultimately commit to the decision. Our meetings were more productive and also efficient, giving us a sense of direction and more hours to do the actual work. As the usage of ADRs became the norm, we could easily apply it to process and people realms as LDRs.

An ADR example

Below is an ADR from my real-world experience. While it seems technical, the intent is to illustrate an ADR template and its different sections. The scenario and certain sections have been simplified for brevity, hence it should be an easy read.

File Name : Shared Drive \ Decision Records \ Tech Design \ ADR-long-search-params-in-request-001.adr ID : ADR-long-search-params-in-request-001 People : Stakeholders (Tech Lead, QA Lead, BA Lead) - these folks are accountable, and primary decision makers - Core team (main team, downstream teams) - these folks are responsible, their commitment is key for the decision - Advisory (Head of Engineering, Architecture Council) - these folks are consulted, their inputs need to be acknowledged - Other teams - these folks are informed, this enables information radiation Proposed By : Developer A - the person who is responsible for driving the decision to closure Status : Accepted Effective Date : 30-Aug-2024 Context : The business needs an API to support an advanced search functionality that involves several dimensions. Decision : Send search params in body of POST request Consequences : This is an internal endpoint, hence non-conformance with RESTful architecture is acceptable. To make this exception visible, custom documentation will be added, and document auto-generation will be disabled. Alternatives : 1. Limit search params to 2000 characters in query string of GET request - (limits business need) : 2. Send unlimited search params in query string of GET request (possible flaky behavior in different browsers) : 3. Send search params in body of GET request (possible flaky behavior due to non-compliance with HTTP spec) : 4. Use two calls, POST search params to store them, use its ID in query string of GET request (over-engineering) : 5. Use a custom HTTP verb (opens up the endpoint to be RPC rather than REST) : 6. Send search params in body of POST request (breaks RESTful architecture by mixing GET and POST)

Wrapping up

In the next (and final) post, I will dive deeper into the async aspect of LDRs and explain how they can facilitate structured decision-making in remote or distributed teams. For now, I’ll leave you with a couple of useful references related to ADRs.

• This repository has a good collection of markdown templates, quick-start guides, examples and tooling
• This page is a good reference for broader context, opinions, tooling, and more opinions