Developer Relations Pyramid: A Tool for Building Developer Programs

DZone 's Guide to

Developer Relations Pyramid: A Tool for Building Developer Programs

In this article, we are going to deconstruct the Developer Pyramid to help understand how you can apply it to your own developer program.

· Agile Zone ·
Free Resource

glass pyramid

Learn how to build a developer program!

Over the past 15 years of building developer programs, I have developed a tool I call the Developer Pyramid to help guide me in managing the developer programs I have helped architect and build. The Developer Pyramid is a simple construct representing how developers learn and engage with platforms, how communities grow, and how programs are structured to support both.

In this article, we are going to deconstruct the Developer Pyramid to help understand how you can apply it to your own developer program, both as a diagnostic tool to improve upon an existing program and as a blueprint for building one from scratch. 

You may also like: Best Practices for Building Great API Developer Portals

developer pyramid

The pyramid itself is divided into three sections. Each section speaks to the infrastructure you need to build to reach and cultivate increasingly more engaged and expert developers. Over the next three posts, I am going to dive deeper into each of these three sections, in the hopes that others use it to diagnose and improve upon existing programs, or to provide a blueprint to the one you may want to build from the group up. 

Let’s start with the base of the pyramid and work our way up. 

The Base of the Pyramid

The base of your pyramid is the most important part of your developer program and will be where you will spend the greatest amount of time and energy building, especially in the early formation of your program. That is because the heights of your program will ultimately depend upon how strong and broad your base is. 

You may be tempted to build other parts of your pyramid as well, but a reason we choose the pyramid for this metaphor, rather than a funnel, is to reinforce the idea that this is a structure that must be built from the ground up. You cannot put in place the apex of the pyramid for example under everything has been built underneath it. 

Supporting Learners

The base of your pyramid will service every developer in your program but will be the most indispensable to the learners within your community. We use the term “learner” specifically to emphasize the following:

  1. Newcomers to your platform are not necessarily “novice” programmers. In fact, it is safe to assume that most developers will be quite experienced. Regardless of their past experience and expertise, every newcomer‘s first need is the same: to learn the basics.

  2. Not everyone who needs to learn something is necessarily new to your platform. Throughout a developer's lifecycle with your product, they will routinely find themselves needing to expand their fundamental understanding of core concepts, best practices, and new product offerings.

Developers, by their nature, never stop being learners. Whether they are explicitly out to learn something, or simply need to verify a method's inputs and outputs, their reliance on the foundation you lay will never truly diminish. 

Building the Base of Your Pyramid

The raw material for the foundation of your pyramid will be the resources developers need to successfully build products on your platform. 


Whether you are a downloadable toolkit or a cloud-based platform, your developers will need a set of products to help them provision, manage and monitor the apps they build. Every platform is different, so it is difficult to anticipate the precise needs of your developers.

It is safe to say that the tools you provide at first should err on the side of simplicity. As your pyramid grows in height, so will your pyramid grow in width. It is then when you can add advanced tooling to your console — like debugging and diagnostic tools, live monitoring, and analytics. 

Documentation and Content

Content is the life-blood of almost every developer program, as it is what will fuel every developer's learning on your platform. As a result, it should be where you devote the greatest amount of energy to building and cultivating. There are many different types of content you can produce, from blog articles and videos to books and webinars — but the core product you need to focus on is documentation. 

I divide documentation into the four categories discussed below. 

Reference Material

If you could only produce one piece of documentation, then the first and only thing you would produce are the reference materials that define the basic inputs and outputs of your system. Without this, nothing else fundamentally matters because nothing can be built without it. 

Quality here matters because shoddy reference documentation will inevitably lead to a burden on your support team, and will hinder community-driven support down the road. Therefore, build a culture within your company in which engineers take pride in their documentation, and maintain it as a natural by-product of their development process. 

Getting Started Guides

Next is the documentation people will consult to orient themselves to your platform. In the grand scheme of things, your getting started content will comprise the smallest percentage of your corpus of content. However, it will also be one of the most important aspects of your program, with the most tooling, and where you may spend the greatest amount of time crafting and optimizing.

This content is important because, for the vast majority of people that flow through your program, your getting started guides will form their first impression of your platform and will be instrumental in how they take their first steps. The ease with which they take these steps will fuel the confidence they will need in order to take the next steps they take. 

Good-Bye Hello World

You can always default to the ubiquitous “Hello World” as your first getting started example. Hello World apps, however, are poor instruments in demonstrating the value of a platform or product. Ideally, you should create content that helps developers perform a fundamental task that not only demonstrates the value of your product but is also relevant in some way to what they may ultimately want to build. 

The code the developer produces through this content will be largely disposable — so try not to get caught up in the details, or in providing content that exemplifies idealized software engineering practices, or design patterns for your platform. Your primary goal should be to minimize the time it takes for a developer to engage with your API successfully for the first time. 

Don’t worry, as a developer’s confidence and expertise grow, they will naturally come to produce code that is more representative of the better coding and design practices they have learned through school or elsewhere. 

Consider the Medium

When producing your getting started content, consider your medium closely. Text is a logical and reasonable place to start, but depending upon your audience and your product, other mediums may prove superior. At Roblox for example, we found that video content was a much more engaging and successful way to help a younger generation use our tools successfully, and Twilio has created an entire video game framework for learning their platform. 

The key here is to challenge your assumptions around text, and don’t always assume that it is what will work best to help your developers get started. 

How-Tos and Recipes 

With a strong base of reference and getting started materials, you can build content that helps developers apply what they have learned to solve increasingly more complex design problems.

In thinking about this library of content, consider for a moment how you were first introduced to Lego.  You probably did not start with the 7,500 piece Millenium Falcon. You started with smaller kits and tasks. These kits were not only fun and rewarding to build, but they also helped illustrate the simple design patterns on top of which everything else is also built. This guided the engineering behind your own unique designs as you began to venture beyond the pages of your instruction manual. 

Your recipes should work in similar ways. Start with content that is more foundational, and over time create content that builds on top of what was created before. Content should be task-oriented and should help developers quickly implement increasingly higher-level application building blocks and components that they can re-use. 

As with everything about the Developer Pyramid: build from the ground up. 

Code Samples and Reference Implementations

Finally, provide your developers with a few fully-functional applications that can serve as a reference for your platform's best practices. You may be tempted to author fully functional, and arguably useful demo applications. While there are a time and place for these apps, rarely will your developers build on top of these products as frameworks in and of themselves, despite our best intentions. Keep these reference implementation simple, and use them to illustrate:

  • How to integrate their apps into a CI/CD framework, how to deploy to the cloud (e.g. Heroku, Google Cloud or AWS).

  • How to integrate with popular frameworks, like Node/Express, Visual Studio, etc. 

As a general rule of thumb, whenever you approach creating a new piece of content, ask yourself, "what is my learning objective." That will keep you focused on the right thing: what is it you want the developer to learn how to do, rather than what is actually getting built.

When all is said and done, the base of your pyramid will start to take shape and should look like this.


Building for Scale

When people go about building a platform, they dream of the many apps their community will build. This, after all, is why they are building a platform in the first place. It is also one of the key measures of success: what your community has actually built.

The desire for this outcome will tempt developer relations teams to build the other parts of the pyramid as well: such as forums and blogs, as well as hosting hackathons and events. Fight this temptation early on, and seize the opportunity to build a discipline around making the base of your pyramid easier to grow and maintain.

Engineering Culture

There is a great risk within every engineering team, especially start-ups where the pressure to ship products is so high, to treat documentation as an after-thought. If there is one and only one piece of advice I wish every product development team would follow it would be to build an engineering culture that values documentation, and that generates it as a natural artifact of the product development process. 

To that end, consider adopting the use of Swagger, or a similar framework for defining your API, and build a development process that requires engineers to take ownership over this resource, and to be accountable for providing sufficient content to allow any internal or external developer to use it successfully.

Have your development process require engineers to take as much care with defining programmatic interfaces, as it does human/user interfaces. Finally, ensure your process requires engineers to contemplate how changes to those interfaces can disrupt backward compatibility and existing implementations.

Laying this groundwork early is vital because trying to build this discipline after other habits have set in and codified is exponentially more difficult.


Your ability to tune, and optimize your program and content will depend entirely upon what data you collect about the developers flowing through your program. Granted, you can always add this later, but you will lose an invaluable opportunity to learn about the developers in your program early on -- an opportunity that will obviously never come again. Plus, you will lose the ability to measure your progress and understand the impact changes you make to your program have, which is essential to proving the value of your work and of the platform as a whole. 

The key milestones to track relating to a developer's early progression on the platform are similar to other funnels in your organization. They are:

  • Account creation. The first step is simple: create an account, assuming your product requires it. 

  • Conversion. Next, you want to know if the developer has successfully engaged with your platform. This may be assessed by their calling of your API or the completion of a tutorial or guide. 

  • Activation. Finally, you want to know if the developer went on to do other things on your platform after they successfully got started. There is no prescription for measuring this, as every platform is different, but a good proxy is often the surpassing of some API call threshold. 

Other milestones and signals are key as well, but we will discuss those as they relate to later phases of developer growth on the platform. 


When you first start, make the effort to support developers directly. Learn from the problems they encounter, and work to eliminate friction from their getting started experience. This will feel very manageable at first as the number of developers flowing through it will be relatively small. If you are successful though, nurturing the learners on the platform will become increasingly difficult and time-consuming.

That is why building in support for marketing automation tools like HubSpot or Customer.io will ultimately prove to be a very worthwhile investment. 

Early on, use these tools to congratulate the developer as they achieve key milestones, and to point them in the right direction for achieving their next one. As your program grows, use these tools to send helpful and targeted content when developers hit a snag, and to assist developers in elevating the quality of their applications once they have been released. 


The base of your pyramid is your foundation; and while it may be cliche to say, it is a universal truth: a building is only as strong as its foundation. Therefore, take time to get this right, because it will only help to make building every subsequent layer of your pyramid easier.

Next Up: Supporting Your Builders

In the next article in this series, we will focus on building the next section of the developer pyramid -- the one designed to service your Builders, or those who have moved beyond taking their first steps and are now intent on creating something original on your platform.

Moving forward we will learn more about the resources and programs builders need, the indicators to look for to signal that a learner is becoming a builder, and how the developer pyramid metaphor will continue to inform the design of your platform and program.

Further Reading

6 Skills Developers Should Build to Unstick Their Careers

Why Every Developer Should Build a Side Project

Top IoT Platform Developer Program

developer relations ,documentation ,developer programs ,learners ,agile

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}