A developer portal is an important enabler of developer effectiveness, which works best when it scales access to critical knowledge and facilitates leadership across the engineering organization. In this article, we explore how to deploy a developer portal in the most effective way, focussing beyond the basic features of the developer portal tool, itself, to the important cultural and practice shifts that a developer portal can enable and the organizational change effort that is needed to support them.
At Thoughtworks, we define engineering effectiveness as a strategy to enable engineering organizations to be more productive, so you can quickly deliver more customer value with less investment. Our view on engineering effectiveness includes, but goes far beyond, engineering “excellence”, developer experience and developer satisfaction.
While most of the industry is focussed on specific hot topics, such as engineering platform tooling and observability, our holistic framework for engineering effectiveness explores six focus areas within the product and engineering value stream, and three necessary organizational enablers to make change at scale. One such hot topic, developer portals such as Backstage, fit into our focus area called “Scaling knowledge and leadership”, reducing waste by enabling people to find information quickly and eliminating duplication of work.
While a developer portal plays an important part in the effectiveness of your engineering team, you’re missing a significant opportunity if you don’t implement it correctly. In the following points, we outline the issues the developer portal solves, what it can’t or shouldn’t try to do, and the success patterns and missteps in implementing one. So, whether you've considered a developer portal but need help knowing where to begin or have tried to implement one without the return on investment you could be getting, here's what you need to know before starting (or reinvigorating) an implementation.
The four major engineering needs that a developer portal supports well:
Integrated search to find things across many different systems that provides access to data in a single place.
Cataloging of information and the ability to retrieve the interesting information needed.
Documentation as code, as close to the dev code as possible, to manage things inside the pipeline.
Scaffolding engine or orchestration tool: a mechanism that enables the delivery of a needed resource for the business.
Engineering teams need to be fully engaged. The platform team has a certain set of expertise, but they don't always have the full story. Engineering needs to be a good “customer” of the platform team, fully engaged and taking ownership for solving their effectiveness challenges. A common failure mode we’ve seen is when the platform organization owns the portal and becomes the arbiters of how everything should be done, but they don’t have the buy-in of the developers or fully understand their needs and challenges. It’s important to have the developer portal vision and prioritization driven by, if not owned outright, by the engineering teams themselves and what they need to do to be successful.
A product mindset is key. Your developers are your end users. You need to understand their pain points and address them. A Capability Maturity Model can be a systematic way to help you discover where to start. The goal is to scale knowledge, leadership and effectiveness, and there may be more valuable frictions to solve first that you don't specifically need a developer portal to address. A developer portal may not succeed if there are bigger effectiveness challenges that are unaddressed.
Take a grassroots approach to implementation. Find out what is causing the friction. What are your developers frustrated with? What is the problem that, if you fix, would help improve effectiveness and satisfaction? Strategies we’ve seen work:
Do a little bit of user research on developer pain points.
Launch a developer satisfaction survey.
Provide a shared forum for developers to voice what they don’t like, then give them the space to work on fixing these things.
Couple the grassroots approach with a top-down culture shift. Leadership needs to create an environment that celebrates and incentivizes grassroots behavior. Without appropriate structural support, a bottom-up approach will fail.
Build confidence in the portal by making it the place developers can go to find answers to problems. Avoid death by a million papercuts by cutting down the venues a developer may need to look to find the information and access they need. Train people to come back by incrementally adding new things that provide value. Use the portal to ease or automate repetitive processes that frustrate developers now.
Create shared ownership of the portal through contribution. A developer portal can help create an environment that allows for everyone to leverage each other’s expertise. Once people start contributing, then they are a part of it and will pour more energy into making it successful. Avoid the one “Mount Olympus” core team dictating recommended practices.
Starter kits impact how you start a new application and how you impact best practices. While a starter kit may not solve all legacy technology problems, they definitely enable teams to consistently start an app using best practices, and if it’s done tens or hundreds of times, that’s real momentum and change. Starter kits are powerful tools that the portal can make discoverable and even automate their use.
Inner sourcing models can help remove duplication and drive innovation. They allow developers to engage across the organization by providing an avenue to share and catalog. The platform engineering organization should be the enabler of pulling in information and enabling the inner sourcing model. Portals like Backstage allow for inner sourcing models to work.
Visibility is the developer portal’s magic. A developer portal implementation at its best is deeply pragmatic and reflective of your organization’s on-the-ground reality. It provides data on what is being consumed and how it is being used. This will catalyze, often surprising, important new conversations and understanding of how things really work in your organization, showing dependencies or creative, pragmatic workarounds to legacy challenges that would have previously been the only in the awareness of a few engineers or architects. When you expose reality, developers often respond quickly and voluntarily with practical solutions that may never have been prioritized. This is where magic happens that you can’t often predict or “manage” your way to. Often, this lowers the barrier of change management and enables new engineering behaviors organically.
When implemented effectively, developer portals serve as a foundational tool to scale knowledge and leadership across the organization and positively impact developer productivity, satisfaction and talent retention.
For more information about our approach to transforming your engineering productivity and optimizing your engineering organization across the dimensions of our engineering effectiveness framework, contact us today.