Using an internal developer portal to make developers 10X and break conway’s law

Introduction

The following is based on an excellent presentation by Dean Shub, who built an internal developer portal at Wix. In it, Shub discussed how to apply product thinking to the internal developer portal, by focusing on the personas that will use the portal, their intent and how to engage with them.

‍

Congrats! You just hired a highly skilled developer. You probably invested a great deal of time to recruit and interview the developer, and now it’s time to begin onboarding. Once the developer joins the organization, it's time to have the developer read the documentation, consult with a buddy on the team and begin getting to know the engineering organization. In our case, we wanted them to set up a system and deploy to production. Now they need to understand the org’s GitHub, generate the repo and begin using the tools used in the organization: open source tools, dev tools, cloud etc. It’s an important piece of the onboarding puzzle but each tool actually reduces the developer’s velocity. They need to learn the tool, the interplay of the infra, and each takes them time. 

When you have thousands of developers, improving the velocity of just one developer has a huge impact as it scales across the organization. This is why we chose to create an internal developer portal.

‍

Conway’s law and internal developer portals

Conway's law says that organizations design systems that mirror their own communication structure. It is named after the computer programmer Melvin Conway, who wrote “Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization's communication structure”.

When we built the internal developer portal we wanted to break Conway’s law. Instead of having each group work on separate systems, with separate golden paths, developer onboarding, methods for addressing the infra and managing software, we wanted to use the developer portal to ensure everyone works on the same user interface, infrastructure and flow. And indeed, the developer portal can and should unify everything into one language and one portal, with one interface, one engineering discourse, one terminology and the same flow for everyone. This is what makes developers 10X developers. It also lets developers ship code independently and reduces friction, cognitive load and unnecessary dependency on other teams.

‍

Using personas to build the right developer flows

How do you build the right developer flows? Let’s start by mapping the types of developers that are going to use the internal developer portal.

The personas that we identified are:

• Mortal developers
• Developer managers
• Devtool developers
• Dev Gods; and 
• The developer portal team

‍

“Mortal Developers” and the internal developer portal

They may be junior or senior developers, and are tasked with the role of writing the business logic for the company or product. Mortal developers are intent-driven, and come to the developer portal to do something. Their goal is to take what they developed and move it to production, fix a bug, improve performance. Understanding intent is an important piece of the product thinking process around developer portals.

Once we identify their intent we can create a progress bar for that intent or flow. It will show them where they are in the flow, and also how many steps remain.  I like to think about the “coffee test” in this respect. This test asks whether a developer can get up and get a cup of coffee once they commit code. When they are back, they should be able to immediately tell what the next step is for them. The developer portal should let the person know exactly where they were, where they stopped and how to continue without too much context switching between systems.

It’s important to note that once you context switch between one system and another, the terminology changes too. The term “Project“ doesn’t mean the same thing in all devtools and systems. These differences can be confusing. When we know the flow we can also ensure that the developer is made aware of the most pressing issues, so we can have a notification that says “you tried to do this action and this is the problem you had and that should be fixed”.

Another important focal point for this persona analysis is to always think how each persona can help drive the developer portal and make it better. In the case of mortal developers, we need to let them provide feedback on their experience with the developer portal - this flow does or doesn’t work, the prompts make sense etc, please add another workflow. Providing feedback should be very simple, not a jira ticket or something like that.

‍

“Dev managers” and the developer portal

Dev managers are the people responsible for the mortal developers: team leads, group managers and the like. 

Dev managers are data oriented. They want to understand the status of their projects. While a developer is focused on one project at a time, dev managers will usually be focused on several projects. They want to see what the status is for several projects and also be able to zoom out and understand how things connect to a broader picture. They need an integration with project management tools, and just like mortal developers, they want a place to provide feedback on the developer portal. 

‍

Dev tool developers and the internal developer portal

When we set out to design our developer portal, this was the trickiest persona to tackle. Dev tool developers are often the most knowledgeable in the organization. They are DBAs, they chose the dev tools, and they are very opinionated. It’s super important to understand that you need to preserve their freedom even though you’ve created a developer portal. You can’t just limit them to a framework, since they won’t engage. The way to solve this is to provide them with added value that would exceed what they can get going DIY. For instance, if they are evaluating a dev tool or CI tool we want to provide them with a seamless integration so that they choose to do this through the developer portal.

‍

Dev gods - what do they need?

Dev Gods are the architects. They want to know what the actual underlying architecture is: what connects to what, and the bigger picture, from kafka topics to dependencies and ownership. 

‍

Last but not least, the developer portal or platform engineering team 

The developer portal team is relatively small compared to the size of the entire organization. For us, this means focusing resources on the developer portal infrastructure. This is the value that we deliver, and adding elements to the portal can be outsourced to other teams. As a result, we need to strategize at every point, given the priorities and personas. It’s super important to provide documentation and tools so that a small devtool team can easily develop their own devtool and add it into the portal without asking the dev portal team to do it. That’s how we leverage the fact that we are a small team providing a dev portal. I only need to approve the new tool for deployment once it’s ready. We also focus on experimentation, there is no way I release anything new without trying it myself. I want to verify that the flow for the developer is very simple and clear.

In this way, the platform team develops the infrastructure and each team can add "plugins" to the UI with different business logic and processes. This preserves the unique knowledge of each team, and respects the fact that only they know how to expose their services to their developers.

The end result is that the "data engineering" team can help the platform team to add additional metrics and actions to the developer portal that otherwise wouldn't be there (because the data engineering team is the expert in this area).

‍

So what did the developer portal bring us?

‍

We standardized our terminology. People can now talk in one language that everyone understands, regardless of whether they are DBAs or developers. 

There is an alignment of expectations around capabilities. Everyone can agree on what you can and cannot do in a project, a server etc. 

Integration is much better, since we ensure that teams create a platfomized API that can be used by other developers.

Discoverability has also improved. In the past,  we used to add a tool to the organization and then needed to teach everyone how to use it. Today it just appears in the developer portal and it appears in the user’s flow. They can then immediately understand the tool and use it correctly. 

When you build the right developer flows, you can break Conway’s law.

‍