Improving Team Efficiency with Architecture Decision Records

"Agile methods are not opposed to documentation, only to valueless documentation."

Michael Nygard

One of Lullabot’s goals for 2021 was to improve and standardize our processes across multiple projects. As an agency with many project-based teams, we believed that we could more efficiently and effectively share knowledge, best practices, and good decisions across teams. Our clients often face challenges with effective communication across teams and over time, and we hoped that a solution for our internal needs would be more broadly useful as well.

We observed that:

1. Since team members often move together as a group over time between multiple projects, many of our best practices were rooted in teams, and not individual projects or the whole company.
2. When faced with equally good solutions to similar problems, different teams would often choose different solutions, making it harder for individuals to transition between the teams.

Could we improve our decision-making process across projects? If so, we expected we could:

1. Standardize our processes for greater efficiency, without imposing undue overhead or limitations on our projects.
2. Improve the onboarding experience for new hires.
3. Give our teams more space to focus on hard, unsolved problems.

We knew that written documentation was the only way to achieve these goals. We needed to find and identify a method of writing documentation that developers loved since, in the end, it’s the developers on our projects who make key technical decisions. As well, we needed to figure out how to foster conversations that would lead to the creation of those documents, while ensuring those documents had lasting value.

A Serendipitous Discovery

We discovered Architecture Decision Records in a bit of a roundabout way. One of our team was working with Home Assistant, and had a (seemingly) simple question: How to install “Home Assistant (Supervised) on Ubuntu”? The answer is documented at 0014. Installation method: Home Assistant Supervised, describing Home Assistant’s installation requirements. In that repository, the decision to use ADRs is documented at 1. Record architecture decisions.

This chain of links ends in Documenting Architecture Decisions by Michael Nygard. Take a moment and read the article before continuing. 

The idea that documents should be “bite-sized” and the focus on documenting motivations, and not just the decisions, spoke to the challenges we’ve had with documentation on previous projects. The fact that ADRs could be public, and should liberally link to supporting resources was intriguing. Could we use this format to build a library of flexible, but long-lived technical recommendations?

Architecture Decision Records: A Step Towards Standardizing?

After reviewing the philosophy behind Architecture Decision Records (ADRs), we identified several technical aspects that met our goals listed above:

1. Developers are used to writing README’s and other technical documentation in Markdown. By focusing on Markdown, and not Google Docs or Confluence templates, it seemed more likely our team would contribute to the process of writing ADRs.
2. The pull request workflow used by most teams works well for the lifecycle of an ADR. Many proposals can start with an issue or pull request. Edits and reviews can happen in a pull request, providing a long-lived record of who was involved in a decision and how the discussion evolved. Relevant team members can approve ADRs with GitHub’s approval workflows. Accepted ADRs are merged and declined ADRs are closed.
3. There are dozens of static site generators able to render Markdown. Ideally, we’d be able to build a website to organize and share our ADRs, without the maintenance overhead of a full CMS.

Our Progress

Lullabot started by forming a working group of interested team members who took on the work of identifying possible standards, discussing them, and documenting them. So far, we have:

1. Completed 15 different ADRs, ranging from “Use Environment Indicator on Drupal sites” to “Use DDEV for local environments”.
2. Discussed many other topics that we determined could not be standardized reasonably across projects, such as multilingual architecture or accessible menu design.
3. Created a new themable Gatsby-based static site generator for displaying decision records.
4. Started to move from documenting “invisible standards,” meaning practices we used on every project but never documented, and towards making decisions that resolve implementation differences between teams.

Other Topics

As noted above, not all topics are suitable for architecture decision records. Some topics may have multiple solutions which are incompatible with each other but are desired by our customers or end-users. For example, some Lullabot projects use Drupal’s Layout Builder, while others use Paragraphs combined with Layout Paragraphs. Standardizing on one solution or the other would impose undue costs on our clients and the products we build. 

After some evaluation, we selected Discourse as the tool to host internal discussions and recommendations for these types of problems. Not only does the product and company match our Engineering Values, but we’ve found that Discourse encourages deeper conversations with greater permanency than Slack. If Slack is sentences, Discourse is paragraphs and citations. 

Over time, we expect some of our heuristics documented in Discourse to crystalize into recommendations we can turn into ADRs in the form of pull requests. Likewise, some issues created in the ADR GitHub project turn into discussions that can’t conclude with an ADR, and we will move those discussions into Discourse for exposure to a broader audience.

The Future of ADRs at Lullabot

We expect to grow our library of ADRs over time and are working at integrating ADRs into our current and upcoming projects. When starting new projects, we will use ADRs to create project kickoff tasks. As well, our support team will start to use ADRs to evaluate how close, or how far, incoming sites are from our best practices. Finally, we plan to start creating project-specific ADRs using the same template.

We hope others in the community find value in the ADRs we have published. We look forward to feedback in the comments below!