Adoption Strategy

Introduction

Over the course of this practical guide, we’ve covered everything related to internal developer portals, from capabilities and requirements to usage and reporting. But even the most advanced portal will fail without a sound adoption strategy. 

This final chapter explores common adoption risks and proven strategies to mitigate them. We’ll look at how to tailor your rollout based on team structures, gather feedback, and gradually extend usage. With the right approach, you can shift from simply launching a platform to actively accelerating development through it.

Common pitfalls in portal adoption

As builders ourselves, we developers have passionate opinions about the software tools we use. Perhaps it’s no surprise then that developers (the end users of an internal developer portal) can make or break a portal implementation. Executive sponsorship is necessary – but far from sufficient – to ensure adoption. 

When embarking on an internal developer portal initiative, there are a few common pitfalls that can derail success if not mitigated upfront:

• Developers reject the portal if it doesn't integrate into their workflows. For example, if the running services view in the portal does not reflect the real state, developers will only get confused by the information displayed in the portal
• Starting with too many features creates complexity and onboarding challenges. Faced with a cluttered portal, developers get overwhelmed and disengage. It’s best to choose the MVP features that would make developer lives easier.
• Lack of executive sponsorship leads to low prioritization and engagement. If leaders don't reinforce the portal's value, developers doubt its usefulness.

Adopting the product mindset

To drive engagement with your portal and avoid the common adoption risks, it’s critical to adopt a product mindset. This means understanding the organizational structure and constraints of your users – and building an iterative, stepwise approach to rollout (as opposed to a “big bang” launch). 

Step 1: Map and understand your team structure

Team topologies – outlined in the 2019 book Team Topologies: Organizing Business and Technology Teams for Fast Flow by Matthew Skelton and Manuel Pais – provide a model for organizing groups to optimize software delivery and collaboration. 

The authors delineate four common team types:

• Stream-aligned teams: Focus on specific business capabilities and align to end-to-end value streams. (For example, a team responsible for the checkout workflow on an e-commerce site. They own the user experience from adding items to cart through payment and order confirmation.)
• Enabling teams: Provide capabilities like infrastructure to assist stream-aligned teams. (For example, a site reliability engineering team that provides coaching and tools to help product teams understand and reduce error budgets for their services.) 
• Complicated subsystem teams: Specialize in complex technical domains like data or AI. (For example, the search infrastructure team maintains the highly complex algorithms, machine learning models, indexing pipelines, and query engines that power search across the company's apps and sites.)
• Platform teams: Offer shared internal tooling/services to accelerate stream-aligned teams. (For example, an internal platform-as-a-service team offers self-service APIs, CLI tools, and dashboards to allow developers to deploy containerized microservices to the cloud without infrastructure knowledge.)

Analyzing how these topologies interact in your organization shows workflow interdependencies. This enables tailoring adoption strategies accordingly. For example, onboarding platform teams first creates a foundation for stream-aligned teams.

Step 2: Tailor your rollout strategy to the goals/structures of your team

Adopting a product mindset serving your internal developer user base involves:

• Conducting developer interviews and surveys to grasp needs and pain points. This provides insights for prioritization.
• Selecting an initial focused use case, like high-value APIs for a critical frontend app. Avoid overwhelming everyone at once. 
• Monitoring usage data to identify adoption obstacles early. For example, low utilization of a new tool may indicate UX issues rather than inherent low value.
• Gathering feedback through surveys and user testing. Rapidly iterate based on developer input.
• Leveraging successful initial teams as champions to encourage peer adoption through their credibility.
• Gradually onboarding more developers, APIs, and tools based on demand rather than a rigid timeline. Let organic growth guide expansion.

The final word

An effective internal developer portal requires more than just technical buildout – it demands cultivating users. By understanding team structures, goals, and pain points, you can craft tailored adoption strategies. This balances breadth of capabilities with simplicity. Through a product mindset, you can evolve your portal from launch to liftoff.

Conclusion: Parting thoughts

Ultimately, nearly every organization stands to reap the benefits of an internal developer portal: superior engineering quality, greater standardization and efficiency, and improved visibility of engineering output throughout the organization.  

This practical guide has covered a lot of ground.  

• We’ve discussed the definition of an internal developer portal and explored the basic considerations – including opinionated vs. un-opinionated, and degree of separation from underlying architecture – that go into selecting the right portal for your organization
• We’ve done a deep dive into the critical features of a portal – including blueprints, developer self-service actions, scorecards, and automations
• We’ve explored the importance of reporting and provided battle-tested recommendations on streamlining portal adoption for your organization

We hope that this practical guide has helped shape your thought process as you embark on your internal developer portal journey. 

So…who are we?

Port is an open internal developer portal, owned by platform engineering teams and built for developers. Port consolidates everything developers need to know and execute to deliver software autonomously and to comply with organizational standards. You can open a free Port account at getport.io.

We’d welcome the chance to continue the conversation. Visit https://www.getport.io/ to get in touch.