So you've just bought a new platform tool? Maybe it's Hashicorp Vault? Snyk? Backstage? You’re excited about all of the developer experience, security and other benefits you're about to unleash on your company—right? But wait…

Because, if you've ever rolled out a developer tool, you know: it’s hard. No matter how shiny the tool. If it’s your first time rolling out a tool, I will guarantee that you’ll make mistakes: you’ll push out your tool too early, or too late, which would compromise your timeline. If you misjudge your timing and communications, you risk users having a poor experience, leaving you to fight to win them back in future. These adoption mistakes at best will stall your adoption, but at worst they can completely derail your project, causing it to outright fail.

In this post, you'll learn

• why running an 'all-hands' demo too early can hurt developer tooling adoption
• why champion-building is your highest leverage for adoption success
• best practices for building knowledge, support, documentation and more.

Adopting a developer tool is hard

How do I know? Because I've been there. Back in 2021, I was part of a platform team that was one of the first adopters of Backstage. I've also seen what it takes to move 4,000 repositories to GitHub Actions (spoiler: it wasn't easy). And these days, I help our customers adopt Gitpod, a cloud development environment (CDE) for their engineering organizations to improve developer velocity. It's no surprise that I see many similar challenges to those I've faced in the past.

Over the past couple of years at Gitpod, I've seen the difference between companies that adopt Gitpod quickly and those that take longer to realize the developer velocity improvements that come with a Cloud Development Environment. So, the big question is: why are some companies faster at adopting developer tools than others? Let's explore that today.

Beware of the early 'all hands' demo trap

One trend that I've noticed teams gravitate towards in the early days is wanting to run demos or 'all hands' calls, typically involving as many engineers as possible, with the intention of a ‘grand unveiling’.

Behold! A new developer tool—in all its glory!

However, as is nearly always the case with these 'all hands' calls, a group of engineers will immediately try the developer tool, and briefly after exploring it before thoughts of urgent pull requests will flash in their minds, soon leading to those developers having their focus pulled back to their urgent and pressing needs of the business. So, how do we avoid this fate?

Assuming that visibility is the main challenge and that excitement alone is sufficient for successful adoption. But the reality is that excitement wanes, and the reality of the business's urgent needs soon takes precedence. And business priorities always win.

There's nothing wrong with demoing a developer tool. But it's the timing of these demos and the narrative you craft can be critical to what happens after the demo. Instead of rushing into demos, what I've found most successful is acknowledging that developer tools adoption is a socio-technical challenge, and to which the most effective pattern we see is champion building.

But, what is champion building? And how do you do it?

You need to start champion building

Adopting a developer tool within an organization is not just a technical task, but a socio-technical challenge, necessitating a strategy that involves people, priorities, and technology. The key to successful adoption lies beyond the tool itself; it's about intentionally engaging engineers and leveraging their surrounding ecosystem for effective adoption.

Why it's so important to "start small"

One of the most critical factors to getting a tool off the ground, is building simultaneously: organic, real and true support from your own engineers, whilst also building a few compelling real-life use-cases. It's usually important you build this foundation before widely inviting your engineering organization to use the developer tool that you're adopting.

Ideally, you start by working with one or two teams or use-cases maximum. You want these use-cases to be shining examples of the future you're trying to create with the adoption of your new developer tool and ideally use-cases that solve obvious and painful needs of the business. Nothing wins over skeptics, naysayers and detractors better than being able to say: "Don't think it's possible? Well let's take a quick tour of how X team are doing things".

The steps to champion building for a developer tool look something like this:

1. Identify internal champions

2. Build one or two compelling use cases

3. Expand and scale

Step 1: Identify internal champions

Find motivated, energetic, and ideally influential engineers within your organization. These champions could be senior engineers like tech-leads, principal engineers, or even junior engineers eager to prove themselves. Look for engineers who are dreamers, who believe in the future, not ones that find solace in the status quo. Once you've got a few champion candidates, it's time for step 2.

Step 2: Build one or two compelling use cases

Now that you have your champions, work closely with them, integrating your tool into projects they are involved in where you will see the highest business return. Ensure the use cases you work on are within their sphere of influence and the champion can be available to assist others. That typically means adopting the tool within a project that your champion works on day-to-day.

It is vital these use-cases are close to your champion's influence, and that your champion has time to support others. Because you will undoubtedly have issues, and will need your champions to be present to quickly resolve them. Time to respond in the early days is going to be very important.

Avoid the mistake of being too distant with early use cases. Pull them close. Not just metaphorically, but physically. If you're a co-located company, sit physically with the champion(s) and their teams.

I've seen this done well with the concept of a "platform team rota", where an engineer does a mini "secondment" into the platform team whilst you're getting things up and running.

As you build out these use-cases the main outcomes you're looking for are to:

1. Grow "institutional" knowledge in your engineering organization

2. Build documentation that connects the tool and your company context

Let's break each of these down a little further:

Grow "institutional" knowledge in your engineering organization

You want to deliberately build knowledge depth of the tool you're adopting with your champion(s). Deep knowledge only comes from using a tool frequently, ideally day-to-day. A great litmus test is when you see your champion(s) answering other engineers' questions quickly and without referring to any documentation. Institutional knowledge will be vital later in your adoption as it can significantly reduce the support burden which otherwise will fall on the adopting team (read: you).

Build documentation that connects the tool and company context

Every organization is structured differently. As you build that institutional knowledge, you want to create documentation which will tie together the developer tool to the specific context of your engineering organization. Most developer tools are highly flexible, so it's not uncommon that you'll need to show how to connect a combination of features to solve certain use-cases.

In the early days it's common for teams to "copy" other teams configurations and setup. Make sure to signpost the best-in-class examples of how to use the tool. If you don't signpost examples well, engineers are going to search in GitHub and copy/paste whatever they find first, which can be difficult to unpick later, and could lead to a bad first-time experience.

As you discover tips-and-tricks, document them. Treat each new engineer as an "experiment" to test the effectiveness of your documentation. Pay attention to the questions those engineers ask like: "Can I connect Gitpod to Vault?" or "How do I login to AWS with Gitpod?". The frequently asked question (FAQ) format works best for these types of documentation.

Focus on providing real-world examples and optimize for copy/paste.

Step 3: Expand and scale

If you've successfully completed the champion-building steps above, you should now have:

1. One or two compelling use-cases of the tool being used in practice

2. Some good initial documentation, most likely in an FAQ type format.

3. A handful of engineers who have good institutional knowledge of how the tool works.

You might want to consider quickly surveying your initial use-case engineers to gather quotes. These quotes can be incredibly useful to influence leadership on your return on investment (ROI) in adopting the developer tool. Social proof is the most powerful currency you have to convince future engineers to switch to a new developer tool.

At this point, running the 'all hands' and focussing on driving visibility to the developer tool can work. Ideally, when planning any demos of the tool, you don't present the developer tool yourself, but get your champion(s) to tell success stories.

Steer the focus of the stories so that you are leading with the value delivered. Showcase what you achieved with the tool, not just what you did. This is a great opportunity to give your champions credit for helping you to get this far with your adoption, and you want others in your organization to see those champions as "the people to go to" for when they need help, support and inspiration.

From here it's a case of working through additional teams and use-cases. Continue the same process of building champions, pulling champions close and iterating on their setups. Do it right, and you'll find with each new team you have fewer and fewer issues. Do it right, and you'll see engineers supporting other engineers and adoption will thrive.

You're on your way to a successful developer tool adoption

Hopefully this gave you some insights into champion-building, which is what we have seen to be an incredibly successful model for adopting a developer tool within an organization. If it's your first time driving adoption of a developer tool, hopefully you now have some more tools in your toolbox.

Remember: Identify champions. Build compelling use-cases. Use early engineers to iterate on your documentation. Give visibility to those champions as social proof. Achieve developer velocity.

Before we wrap up, I wanted to takes a moment to pay a special thanks to the folks who helped proofread and provide additional insight into this blog post:

• Josh Gavant - CNCF Platforms Working Group
• Simon Emms - Lead Platform Engineer
• Bryan Ross - Executive Advisor
• William Ghelfi - Senior Software Engineer & Gitpod Community Hero

So, as always, thank you ! The tech community never ceases to amaze me with it's generosity.