Key Highlights

• Internal Developer Platforms (IDPlat) streamline software development across the entire Software Development Lifecycle, while Internal Developer Portals (IDPort) provide a centralized heads-up display for developers.
• Both reduce cognitive load: Platform by automating tasks, Portals by consolidating access to tools and resources. Both provide golden paths to production.
• The right solution depends on your specific needs and goals.
• Integrating existing tools and gaining buy-in from stakeholders is crucial for successful platform and/or portal implementation.
• When implemented strategically, both tools can optimize workflows and enhance the developer experience, leading to higher productivity and software quality.
• You can start with one and grow into using both.

Basics of Internal Developer Platform and Internal Developer Portal

Since we launched Flightdeck we've heard a lot of confusion about which is which, where to start, and how to evolve. We believe there is no single answer. In fact, when speaking with customers we often advise reviewing the existing processes, tooling and what is working...or not. That generally highlights a few gaps that can be addressed as quick wins.

An Internal Developer Platform (IDPlat) acts as a comprehensive solution, or more often suite of solutions, that streamlines various aspects of the development workflow, offering tools for deployment, monitoring, and collaboration. Core here is automating and streamlining each step in the development lifecycle. This isn't just about deploying a continuous integration tool or orchestrator. Rather, it is reviewing the friction points in the development process from initial commit all the way to retiring software, understanding where you can standardize, what flexibility to offer, what products to buy and what to build. It is a large effort that isn't typically one shot and done. Rather when we talk about IDPlat we talk about it hand-in-glove with Platform Engineering as a wholesale way to evolve developer tooling and experience over time.

On the other hand, Internal Developer Portals serves primarily as a heads-up display where developers can access resources, documentation, and some automation to aid them in their day-to-day tasks. While there is certainly some effort in adopting a Portal it is lower effort than developing a comprehensive Platform. We view a Portal as a critical part of a platform, and typically the best starting point on that journey, as it provides quick time-to-value for most situations. If done correctly it makes the Platform journey easier.

The Functionality of an Internal Developer Platform

The platform is usually a collection of tools which comprise the whole SDLC. Because of this, we often see the Portal act as the display tier, with the platform engineering team building and operating most, if not all, of the platform components. This is not a 'all in a box' situation for most companies as the functionality spans from source control, code quality, testing, CI/CD and infrastructure all the way to running and hosting services. Heck, we've also seen companies pulling observability, AI tooling and PaaS tooling into the mix as part of this effort. Sounds like a lot? It is. That is why we generally don't advise companies to start here.

The primary goal of this effort is to reduce the cognitive overhead and the friction developers experience dealing with so many tools and processes. In turn, this allows development teams to concentrate on important tasks like value creation and innovation, instead of getting stuck in complex operations or chasing access. The net result is a modernized end-to-end system, with developers experiencing most of it from the comfort of their IDE.

The Functionality of an Internal Developer Portal

If a Platform is the umbrella then naturally the Portal fits under it. It provides developers with the display tier, a near-real-time view of their software estate, relationships, dependencies and tooling. It typically provides the entry point for golden path provisioning of new applications, via ready-made workflows using something like the scaffolder in Flightdeck.

We think of the software catalog as the most critical part of both the Platform and the Portal. It's kinda hard to manage and maintain software you don't know about or understand the relationships between software and systems. It gives developers a heads-up view to use all the different tools, services, and relevant documents in their environment. By bringing these important resources together, the portal makes the developer experience much better. Often just getting things into the software catalog is the biggest win. Chasing spreadsheets and out-of-date wiki's is a grind nobody wants to deal with.

A good portal should be easy to use and clear. It should show developers a service catalog to find and understand the services and relationships in their environment easily. The documentation should be relevant and easy to read. The whole thing should also be self-service.

This smoother developer experience reduces the time spent looking for information or waiting on help from another team. It builds a culture where developers can be self-reliant and work collaboratively.

Photo by Sigmund on Unsplash

Evaluate Current Developer Experience

Assessing your existing developer experience is crucial. Arguably this should be step one. Identify current cognitive load, workflows, tools and dependencies to gauge interaction complexity, latency and frustration.Where are developers getting stuck or facing impediments? What parts of their workflow just plain sucks? What is manual that could be automated? Map each team's workflow. Odds are that there are some dark corners here and now is likely a good time to fix that.

Admittedly, a wild card that is hard to assess is the cognitive load each team member experiences. This will vary based on their own experience level, understanding, workload and tools. No two people or teams are alike here. Based on the teams expertise and load, you may be able to bite off more or less work.

Lastly, we think ease-of-use is fundamental but ease-of-use maps to existing skills and workflows, not an obscure standard. So involve the teams in decision-making early because the current state of the teams, their learning curves, and level of cognitive load will either hinder or help streamline your journey.

This should give you a toehold to understand user needs and capabilities, which in turn informs where to start.

DevOps or Platform Engineering, Who is Running This?

We often find ourselves discussing whether it is necessary to have a platform engineering practice in place before starting this journey. Plenty of benefits if you do, but it isn't required.

Either the DevOps or Platform Engineering team plays a crucial role during the planning phase. They are probably well-versed on scalability, security, automation, and deployment requirements. Take those results and evaluate if buying or building makes the most sense for each part of the overall platform. We tend to think this ends up being a blitz and blend scenario for most companies.

The underlying infrastructure requirements will inform how to proceed with each component. For instance, some vendors can support complex tenancy and data isolation models while others anticipate you dealing with that yourself. This sort of limitation needs to be assessed against the team's proficiency in infrastructure management, automation tooling, and ability to develop complex add-on elements for the platform. You need to understand where the capabilities and gaps exist here as well.

Moreover, the DevOps or Platform Engineering team's emphasis on best-practices. such as version control, automated testing, and deployment pipelines, helps maintain code quality, reliability, and security within the Internal Developer Platform. Their ability to adapt to evolving technology trends and business requirements ensures that the platform remains agile and responsive to changing needs.

Overall, the DevOps or Platform Engineering team's dedication to driving efficiency, collaboration, and innovation makes them instrumental in shaping a dynamic and developer-friendly environment within an organization.

Selecting the Right Starting Point

Put simply, where is the largest existing pain point? For many companies this lies in the discovery of software and systems. Teams spend a surprising amount of time waiting on access and searching for up-to-date information about the dependencies, tooling, documentation and people that are working collaboratively within the software estate. It is not unusual for this discovery to be a manual processes that results in errors, omissions, or, worse, production defects.

Also evaluate the organization's capacity for change; determining which will be most or least disruptive for your team. Taking a portal-first approach is generally minimally disruptive because it doesn't initially make significant changes to the tools developers work with on a regular basis.

Integrating Existing Developer Tools

A successful platform or portal installation depends on how well it works with your organization's existing investments in tools and workflows. Platform engineers need to look closely at the current development process and plan on an integration strategy. What is the source of truth? What tools need to be integrated with what other tools? And, how are you establishing end-to-end visibility, rather than retrenching silos?

By adding current tools into the new platform, companies can continue to use what they already have. This helps avoid disruptions to existing workflows. For example, they might integrate source control systems like GitHub, CI/CD tools like Jenkins, or Infrastructure as Code solutions like Terraform.

The important part is to plan to carry out the integrations based on a clearly defined end state. Focus on automation and ease-of-use. This will help ensure a smooth change and boost overall productivity.

Getting Buy-in and Driving Adoption

As we've noted it is important to get support from everyone involved. This includes developers, platform engineers/DevOps, and business leaders. You need to clearly explain how the platform will help the business. Show how it will make work easier, enhance the developer experience, and improve overall visibility and understanding of the software estate.

Ever wonder why executives don't talk about software? It's because they can't. The visibility isn't there the same way it is for finance, HR or real estate. That needs to change.

Many companies benefit from having a product manager lead a platform initiative. Shifting to thinking about the internal elements, along the lines of a product, helps understand feedback and drive continual improvement over time. Product managers are used to consolidating feedback and providing vision. This builds trust and helps more people to adopt your collectively-chosen path. Similar to platform engineering, a product manager isn't strictly needed for a portal project but is highly advisable for a platform scaling effort.

Can an Internal Developer Portal evolve into a Platform?

Photo by EJ Yao on Unsplash

Yes, and, admittedly in our biased opinion, this is the smart approach. A portal can be integrated into a comprehensive platform later if the portal has the necessary API's and integrations to be leveraged in this manner. These capabilities help with future integration and automation and, in the end, should be a key criteria for evaluating internal developer portals.

After all, if you can't extend or automate it how long is it going to provide value? We've focused on a GitOps and API-centric approach with what we are building, and we've found most platform engineering teams prefer that to a "ClickOps" approach. This was a deliberate choice, knowing that extending into a broader platform will be cumbersome otherwise.

A portal can start by organizing documents and data and extending situational awareness. Over time, it can add functions like automated deployment pipelines via a scaffolder or integrate with a reporting tool, like Jellyfish, to provide deeper metrics about software engineering. By adding these features, the portal starts to look like a platform, and this is often how that evolution starts.

This change usually depends on what the organization needs and how it grows. As development teams grow and projects get more complicated, use cases beyond the initial portal develop. These features help improve workflows and give better control of the software development process. However, making these changes needs thoughtful planning and careful action to keep everything running smoothly.

Over the coming years we expect most of the existing development toolchain to evolve. More API's and Generative AI will play a huge part, and we've planned this out within our products so our customers will have an easier time making these adaptations. When planning out the evolution from your current starting point to the end state make sure you fit elements of what looks like the distant horizon into the mix. It's coming faster than you may think.

Conclusion & Next Steps

In conclusion, while it is important to know the difference between Internal Developer Platform and Internal Developer Portal, it is equally important to understand aspects of your current developer experience and deployment strategy for new technologies. This knowledge gives a baseline understanding to measure progress against and also helps inform the right tooling. By choosing the right starting point, using the tools you already have, and encouraging people to adopt new systems, you can make your development process more comprehensive while simultaneously reducing toil. As you plan things out, keep in mind that evolving from a Portal to a Platform is possible if you plan well and use your resources wisely. Both support your developers and increase productivity; they just take slightly different approaches.

TL; DR Summary

What is the main difference between an Internal Developer Platform and a Portal?

It is easiest to think of an internal developer platform as a collection of tools and automations that helps development teams automate the entire SDLC. An internal developer portal is primarily the display tier for the internal developer platform. It provides much of the data, via the software catalog, and integration elements needed for improved automation. But, over time, these data points and integrations help to extend into a more comprehensive internal platform offering.

How do I determine which solution best fits my team's needs?

• Look at the biggest problems your team has.
• Evaluate team capacity and capabilities.
• If access, documentation, understanding of the existing software estate, overall developer experience, and/or cognitive load are primary pain points, make an internal developer portal a priority.
• If you need to modernize large parts of the SDLC toolchain, simplify workflows and improve automation, then focus on an internal developer platform.