How GitHub, Spotify, and eBay use ADRs and Tech Radars for technology decisions (Video & Slides)

Let’s face it, roadblocks often make it challenging for software engineers to collaborate. Even within development groups that have adopted agile methodologies, coding is often a solo effort. What developer hasn’t become so immersed in a coding project that has spanned 5 cups of coffee and several missed meetings? And during that solitary affair, many developers make technology decisions, such as platform or tool selection, in a silo.

Those decisions may be okay for the engineer working by themselves, perhaps on their own project, but most career software folks are part of larger teams, in larger organizations that include product managers, quality assurance, operations, and more. In an ideal world, wouldn't it be valuable for everyone to be on the same page when it comes to the technology decisions related to the products they are going to launch or support?

“80% Planning, 20% Coding”

Many developers grew up programming on their own, oftentimes not taking the time to develop specifications prior to jumping into a project, building it. Part of the process, the part that gets creative juices flowing, is just doing. Select technology. Try it out. Rip it out. Hack it. Tweak it. Bend it to your will. But that doesn’t really work in a functional business environment. Sure, pure innovation, such as in a hack-a-thon, has its place. But to productive development, planning must take a central role. IBM said it best, back in the reign of Rational Rose: if you spend more time planning, you waste less time coding.

The same can be said about selecting technology, whether it’s for a specific product or an entire platform. More time spent planning up-front, discussing the pros and cons of technology options, results in less risk to the project, and the business overall.

The Tools for Technology Planning

Thankfully, there’s a solution to help you plan the discovery, assessment, and selection of technologies within your product stacks. Two solutions are starting to gain popularity in the software development world amongst companies like GitHub, Spotify, eBay, and CNCF: 1) Architectural Decision Records (ADRs) and 2) Tech Radars.

ADRs are really just a record of what’s been decided. In some cases, like for open source projects, this can be published as part of a repo to document the decisions made with reference to embedded or included technologies. ADRs answer basic questions like,

  • What was the context in which the decision to use this technology?
  • What were the risks for selecting this technology?
  • What were the benefits for selecting this technology?

The great thing about ADRs, whether they are public or not, is how much they can help incoming developers. On-boarding time can be significantly reduced, and anxieties can be mitigated, when software engineers understand the “why” of a technology selection. Just imagine it: you can give an incoming developer a bunch of ADRs so they can get up-to-speed on the technology being used prior to ever sitting down at their desk.

But ADRs also do something else which is important in today’s corporate development culture: they foster collaboration. When there is a forum to discuss technologies, developers have a chance to be heard as well as a way to have a say in the more fundamental elements of the company.

Tech Radars, in comparison, reflect the landscape of available technologies. As the old adage goes, “you don’t know what you don’t know.” That is no more true than in technology. New platforms, new approaches, and even new languages, seem to be popping up everyday. But are they all worthy of attention and effort? Remember that part of that ADR is the selection of a technology. That means it needs to be tested and reviewed. But if there are a hundred options, they can’t all be reviewed. There needs to be a filter. That’s the Tech Radar. By segmenting available technologies in specific groupings (i.e., platforms vs. languages) and then assigning them a value, such as Trial, Adopt, Assess, and Hold, it is vastly easier to whittle down the list of possibilities to just a few.

To dive into ADRs & Tech Radars even further and how large tech companies are using them, watch this talk from our Founder & CEO, Yonas Beshawred.

Slides from the presentation:

What Do You Get Out of All This Planning?

Having a technology selection and documentation process saves your developers time. They will spend less time searching around for solutions and more time coding. These ADRs and Tech Radars become the “source of truth” for the technology stack within your products. And time, as you very well know, is the most precious commodity of all in software development.

Using Tools to Create the Tools

Using ADRs and Tech Radars can be time intensive. And when a project timeline is littered with development milestones on a time schedule, it can be difficult to break away and gather up the troops to talk about planning. In fact, you might have to physically pull developers away from their computers, especially when they are deep in the Flow, to get them to come to the table. So what if you had a tool to help you build those planning tools? What if there was a way to cut down on the manual parts of the ADR process, such as writing them out, or the process of building a Tech Radar?

That’s exactly what Private StackShare for Teams can help you do.

Private StackShare for Teams helps you automatically document technology decisions as they happen (via Pull Request integration) and allows you to replace manual Tech Radar spreadsheets with dynamic labels and profiles. You can learn more about it here.

Without ADRs, Tech Radars, or Private StackShare, you could face some tough decisions down the road, like ripping and replacing tools, that could have been avoided with a little more up-front planning and documentation.