Every December, we try to pay some attention to documentation. It feels like a good end-of-year focus: creating docs encourages you to reflect, organize, and prepare for future growth.
We also know that, in the hustle and grind of your regular workflow, documentation can often meet the fate of many other resolutions. Nagging anxieties aren’t good for your productivity, either, so we’re not here to guilt trip you. You know documentation is important. And most API teams who are falling behind on docs aren’t doing it intentionally—finding a process that creates useful docs without feeling like a burden isn’t easy.
That’s why we’ve been interested to read about a model called Architectural Decision Records (ADRs). Let’s note up front that ADRs are not a replacement for the kind of user-facing documentation that you need for a great developer experience. But ADRs can be an efficient and powerful tool that supports many other aspects of your API program.
Make Architectural Decisions as Traceable as Bug Fixes
When you discover a bug in your API code, you probably follow a standard routine of tickets or issues, commits, pull requests, code reviews, compliance checks, and merges. It’s a time-tested process that makes it easy to track how code changes over time and helps ensure additions to the code base are compatible with existing standards and functionality.
ADRs are similar, but they focus on higher-level decisions about product architecture and standards. The ADR process, which is used at organizations like AWS and Spotify, is intended to create a traceable, immutable record of the decision-making process for choices around security, dependencies, frameworks, microservices, and other big picture issues. Without a process like this in place, many organizations only document whatever the most recent choice is, and they may not record the context and purpose of the decision at all.
The rationale for documenting high-level decisions is twofold. First, the documentation routine encourages a more reflective, purposeful decision-making process, hopefully leading to a more cohesive code base. Second, the records provide a point of reference for anyone seeking to understand how the project came to function as it does, creating more continuity as team members come and go.
The advantage of the ADR process is that it emphasizes brevity and focus but treats each update as a separate, immutable record so that ADRs can be created quickly as decisions are made. It’s similar to how good individual commit messages communicate a clear action and purpose in just a few words but tell a larger story when seen as a group.
Feed Your Docs Needs
The ADR process has value in itself, as systematizing the way you document decisions can improve the quality of the decisions themselves, according to some research. But we’re talking docs—and we want to highlight how ADRs can set you up for a much healthier documentation practice.
Empower Internal Stakeholders
Olaf Zimmermann, an early advocate for ADRs, cites a relatable story to explain the value of ADRs. Imagine a consultant joining a new project. The development team uses an agile approach. Before the start of the next sprint, the consultant wants to understand some of the key architectural decisions behind the project. But things have moved so fast that there are few records. It’s difficult or impossible to get the relevant people together to provide an authoritative answer, so the consultant has multiple repetitive and contradictory conversations and winds up with little clarity. By the time she has hunted down a definitive answer, the sprint is halfway done.
Internal stakeholders—that consultant, but also new team members who are onboarding, executives overseeing multiple products, and others—all stand to gain from ADRs. An ADR process won’t replace other internal docs, like change logs or ReadMe files for individual repositories, but it can provide an easy way to tie the details in those docs together into a cohesive narrative that’s readable to all stakeholders. Centralizing that knowledge creates a lot more efficiency and reliability in any conversation about design decisions.
Another powerful aspect of ADRs for your internal stakeholders is that contributors need no specialized tools or domain knowledge, and they can create an ADR without an ongoing time commitment. Writing ADRs can become a standard part of developer workflow without requiring much more investment than writing an email. And according to Michael Keeling, ADRs can be a stepping stone to a more sophisticated product design process, even within the constraints of an agile workflow.
Provide Answers for API Consumers
Imagine a different scenario—you are releasing a new API product with some significant design differences from your other products. You task your developer relations team with generating enthusiasm for the new product, but they quickly encounter some pushback from customers who don’t want to have to learn a new standard. Your DevRel team isn’t part of the product development process, and it doesn’t have ready answers for these customer concerns.
You likely don’t want to share your ADRs directly with customers, but they still can help you in this situation. If your DevRel team has access to your ADRs as they are created, they can proactively anticipate potential sticking points for users and create content to address those concerns. When they get questions they didn’t anticipate, the ADR is a quick, reliable way to get the details they need to provide credible information to customers.
Good developer experience includes explaining how and why your product architecture has changed over time. Not every developer will want that information, but as your API consumers build increasingly complex microservices architectures of their own, an in-depth understanding of your product architecture is important. And again, while ADRs may not be the form factor you choose to share this information with external stakeholders, having them will let your content teams produce documentation to meet this need with less back and forth.
Create a Documentation Practice That Lasts
You’ll have to answer for yourself whether ADRs are the right fit for your organization. ADRs can prove useful for a diversity of needs:
- Small teams and startups may not have dedicated documentation teams yet, as they create a record that can be translated into other formats later on.
- Large organizations need to reduce repetitive work and communication by making it easy to share the rationale for decisions across departments.
- Teams working on architecturally complex products within a consumer-technology-driven environment should always represent the current status of the product.
- Product teams expect to change architecture as a product scales.
- Teams with high turnover or significant numbers of external stakeholders
Whether or not ADRs are the solution for you, know that improving documentation practices for your API program doesn’t have to be an all-or-nothing effort. There is no perfect tool or practice out there, but incremental steps like this can set you up for even more improvement in the future.
Maybe you think of documentation as a fairly static practice. In fact, information architecture is an evolving field, and it’s worth spending some time researching ADRs to see if they might be a good fit for you. If not, your research may lead you to other practices that better fit. The docs model that’s right for you is the one you’ll stick with, just like any resolution.
If you’re interested in learning more about ADRs, check out these resources:
- The ADR GitHub Organization
- Architectural Decisions — The Making Of by Olaf Zimmermann
- Documenting Architecture Decisions by Michael Nygard
- Documenting Architecture Decisions by Fabian Keller
- Love Unrequited: The Story of Architecture, Agile, and How Architecture Decision Records Brought Them Together
- Sustainable Architectural Design Decisions by Huy Tran and Olaf Zimmermann
- Using Architectural Decision Records to Streamline Technical Decision-Making for a Software Development Project by Darius Kunce and Dominik Goby (AWS)
- When Should I Write an Architecture Decision Record? by Josef Blake (Spotify)
- Why You Should Be Using Architecture Decision Records to Document Your Project by Heiko W. Rupp (Red Hat)
And if you’re interested in learning more about design-first APIs, check out the Stoplight API Design Lifecycle Hub! We have lots of resources and tools to help you move your API programs forward and create a better developer experience for your customers.
