Engage developers for better platform adoption

You already know that a well-adopted, well-built technical platform can speed application delivery, allow for increased security, and embed compliance and brand standards across applications — if developers will adopt it. The key is to implement a product approach, empowering developers and building their confidence in your platform with outreach, documentation, and support for developers.

To ensure your platform is used to its full potential and that your agency receives the big returns you’ve been promised, you will need to treat your platform like a product. Begin with user research to inform and prioritize your platform’s design and build work from the beginning. Think of your developers as customers, and prioritize their experience as critical to product success. Make sure your platform functions seamlessly with the surrounding services it integrates with. And lastly, approach the launch and adoption of your platform as its own critical initiative.

The best built platform in the world will fail if developers don’t know it exists. Similarly, developers won’t advocate for your platform if it’s poorly documented or unsupported. They won’t use it if they aren’t absolutely certain that doing so is easier and better than coding their own solutions.

Just like an external product would need to be marketed to be successful, so will your platform need specific support to earn user confidence and ensure adoption. Yet, the State of DevOps report finds that most organizations are under-investing in communication and evangelism for their platforms, leading to struggles in more than a third of teams. Your teams should not need to struggle to see the value from your platform. Take the time to create outreach plans, documentation, and support that evolve as your platform does. Together, these will make the platform easy to find and easy to adopt.


Developers and stakeholders will need to hear about the platform before they will “buy” it, just like external customers do. To fully adopt the platform, they must be aware that: (1) it exists, and (2) it will help them with their daily work.

Awareness comes from consistent communication. Plan for targeted outreach across several channels, so that people will hear about the platform in their preferred communication medium. Look for opportunities to share again later: when your users hear about your platform consistently over time, that builds confidence that your platform continues to be an actively supported resource they can use. In most cases, we recommend also doing a “road show,” meeting with each team and letting them know about the platform and its benefits to that team. Use synchronous and asynchronous forms of communication, and short-term and long-term formats. Meet people where they are.

If you do this properly, it will feel as if you have overcommunicated. When you’re starting to feel tired of talking about your platform, that’s when your developers will finally start paying attention.

Knowing where and how to find the platform

People will not use a platform that’s hard to find. We recommend creating an easy-to-remember URL that leads the developers through the process of getting started. Each time you talk about the platform, through communication outreach or the personal roadshow, point people back to that easy-to-remember URL. If you mention the platform in your newsletter, include the link. If you go team-to-team in your roadshow, mention the site location every time.

Communicating clear value

Developers are busy, and often cognitively overloaded. When you talk about the platform, consistently lead with why it’s useful for the developer, and how it will reduce the cognitive load of their work — rather than how it will benefit the organization. Use the opportunity to convince your “customers” that your platform will make their jobs easier, and they will adopt its use.

If the platform delivers different value for different teams, talk to each team in terms of how it helps their specific work. Include these high level statements of value every time you discuss your platform, and in all of its initial documentation. Your platform is a product, and that product needs to be marketed to be effective.

Outreach over time

As your platform evolves, keep communicating with your developers. Just like the updates to your phone’s operating system have clear release notes, so should your communication about platform changes. Make sure people know the value you’re bringing to them on the platform, what processes are changing and why, and which long-awaited new tools they can start using tomorrow. Continue to use a multi-channel approach: newsletters, meetings, and even a roadshow again for critical updates can all be important.

Your approaches to outreach may change over time as well. Measuring the effectiveness of different forms of outreach can help you adapt or grow your communication channels as you learn what works best for your audience.


Another core aspect of productizing your platform is documentation. By providing clear explanations of how to use platform services in plain language, you empower developers. They become able to complete tasks described by your documentation without outside help and with minimal frustration.

Treat the documentation as part of your product by testing the documentation with users. Watching where a developer gets stuck, when something is unclear, or when they turn to Google for clarifications can provide immediate feedback for improvement. The only way to be sure that your platform is easily understood is by getting feedback from actual developers new to the project, and making adjustments accordingly.

Clear documentation is often deprioritized by platform teams in favor of building the next new feature, but it’s mission critical. Either dedicate a technical writer to the team who can focus on writing and maintaining documentation, or prioritize time for the team to do this work. Treating documentation as part of your product means accounting for it in your project’s scope. Building an exciting, large toolset that users struggle to use is a long path to failure. A smaller toolset that is easy to use and well adopted will deliver far better outcomes.

As your platform grows, be sure to keep your documentation current. Make sure developers can follow along without having to figure out on their own what’s changed to the tooling over time. One easy way to help documentation stay up-to-date is to keep documentation checked in and version-controlled alongside code, making it easier for developers to update both together. Pairing this with CI checks that ensure API changes are accompanied by documentation updates helps enforce this practice.

Out-of-date documentation is frustrating for both your developers and your support team, and will significantly decrease developer confidence in the platform’s offerings.

Developer support

Just like external customers of a product, developers will need customer support when they run into issues. To put it bluntly, platforms that are not supported are not adopted.

We recommend dedicated people who can provide hands-on support and answer questions in close to real time, so that developers who are relying on the platform can accomplish their tasks quickly. But you probably won’t start there.

As your platform grows from small to large, support will also need to grow. For example, you may start with an internal chat channel (like Slack or Teams) for support issues, with support needs managed by engineers on the platform team. Establish a weekly rotation for one engineering team member to take point on responding to those issues, spreading the support load across the team.

As support requests grow in number, you will likely find the need to implement a support ticketing system, again with established patterns for ticket assignments and triage. This allows the teams to better track the types of requests they’re getting, and scales more easily across large organizations.

Finally, as platform adoption grows, so too will support needs. Having the same team both build new tools and provide customer support to existing tools will become unfeasible. Velocity will suffer and teams report high levels of stress as they are torn between competing tasks. Splitting the support and build responsibilities will lead to better results for both teams and users. At this point, it’s time to create a dedicated support team across channels convenient for developers. In many cases, this team can also lead your outreach efforts.

In all of these stages, your support channels can serve as a crucial source of user feedback—generating a feedback loop for platform teams about the pain points users experience building applications. These insights will help the platform team prioritize upcoming improvements to the platform.

Success comes from adoption

At Ad Hoc, we’ve supported agencies through every stage of platform build-out, adoption and maturity. We’ve seen those agencies who intentionally build good developer experiences come out ahead, getting far better outcomes than those who prioritize feature building over the strategic support choices that make the platform viable.

Treating your platform as a product helps you earn user confidence with outreach, documentation, and developer support. With a little effort, they will begin to use, and then to advocate for, your platform. Ultimately, your developer experience enables faster, better digital service delivery towards your business goals.