Our Blog

Building a developer portal

Best Practices for Building a Developer Portal

April 23, 2019 - Content Marketing, influencer content marketing, Practitioner Marketing - , , ,
By: Chris Riley

It used to be that the only types of businesses that had to worry about having a developer portal were those which sold to developers. The second cohort of portals was made up of companies that had tech products and an API. But now, unless you are only a brick and mortar retail shop, you are thinking about how to engage with and work with developers. But for those that do not directly sell to developers, building a portal is not as natural as it could be. This post includes some best practices for building a developer portal from the ground up.

Know your audience

The first thing every organization needs is to know their audience. The developer does not approximate the typical customer. They are impatient, critical of everything, and expect a lot. This translates into your portal in the form of adoption. The portal needs to cover all aspects of the developer journey (as listed below), and needs to mitigate frustration.

The developer’s journey

The developer’s journey is the path a developer takes to go from knowing who you are, finding a way to use your API/framework, and then finalizing a solution and being a huge fan. When you build a developer portal, you need to be able to cover the entire journey—but even more importantly, support a user at any possible point of entry. The following are the stages of the journey.

  • Heard about the tech: From a peer or online techies, the developer will discover your API and have an interest to learn more. Usually they see an opportunity, or they just think it is cool. It’s easy to engage a developer at this point, and you have a lot of leeway.
  • Dabbling: The developer will likely build a “hello world” type application. The product will likely not be a long-term application, but a good go/no-go to keep playing.
  • Starting building: After they have validated that they can build a hello world application, they will probably identify a project they are interested in completing. Hopefully it’s not just a hobby-based project. Makers are good for awareness, but not much else.
  • The trough of despair and bugs: Once the developer starts building their application, they will inevitably hit a point where your project is a new favorite curse word. They have found bugs with your API or their application. They are trying to do something no one else has before, etc. This unfortunately is a natural part of building any application. You can’t prevent it, but you can be supportive.
  • Refinement: Once they start to get their groove back, and solve some major problems, their enthusiasm is either at an all-time high, or they have moved on and dropped the project. Assuming things are good, then the developer is a big supporter who is going to sprint to the finish line.
  • Completion: Finally, they will consider their app or feature done. What they do beyond this is critical—both to the success of their solution, and how they amplify your portal.
  • Sharing: Now it’s time to socialize what they have built internally (for a customer base), or if it’s an open source project—for the world.

The developer’s journey is not just steps. It is also associated with emotions, personas, and directly ties to content.

Top 3 business considerations

Building a portal is not about throwing a site together and making sure that the right amount of content is there. It requires more.

  1. Create a budget: For companies that do not sell to developers, this can be rough. Because it does not directly relate to the bottom line, you often are not given a budget. But most organizations realize that with a few jumps, it does hit the bottom line and reputation of the company. Fight for a budget. Without it—like practitioner blogging—there really is no point in beginning.
  2. Taxonomy/Information architecture is important: To meet the expectations of the developer’s journey, how you structure the content is just as important as the content itself. A predefined and flexible information architecture is an important first step.
  3. Don’t assume their entry point: The mistake a lot of organizations will make is that their portal is all about documentation, or all about use cases, or just promotion. It needs to have the appropriate blend of all of the above. If it’s just docs, it will only appeal to existing users of the API; if it’s all use cases, no one will be able to go deeper; if it’s just promotional, then no one will ever get started. They will have a lot of enthusiasm and nowhere to spend it.

Structure—Align to the Journey

Here are the key content components of all developer portals:

  1. Use cases: Promotional material on why the framework is used. This may have to be tailored to specific common examples, including verticals.
  2. Concepts: Sometimes APIs require specific prior knowledge. But this should not be a barrier—because it does not mean it’s only available to those with that knowledge. For example, in the auto industry, you might need to understand some things about technology in cars and how to leverage it. But the app you build might not be an auto app. For this reason, you need to give developers a way to be easily educated on concepts relevant to the core of the tech.
  3. Running code samples: These are already “compiled” and running examples of the API in action with existing apps. They should require no effort to get up and running, with code immediately available for inspection.
  4. How-tos/Walkthroughs/Code samples: These are similar to use cases, but adaptable with step-by-step examples or modifiable source code that developers can use to build the skeleton of their application.
  5. API docs: These include the nitty-gritty details and internals of your API—no fluff, just direct information on what API calls are available, how they work, and one-liner examples in common languages.
  6. Case studies: Real-world examples of how developers have used the technology. There is no better way to learn tech and have confidence in it than learning from someone who has already gone through the journey.
  7. Community/Support: This is the aspect that many organizations see as a runaway train of effort and cost—and it can be if it’s not structured with the appropriate guide rails. But community and support have to be there to make sure that when a developer hits a wall, he or she has an option to move forward.

All of these components need to have relevant, timely, accurate, and consistent content. Here is how they align with the developer’s journey.

  • Heard about the tech:
    • Use cases
    • Running samples
    • Practitioner Blog Posts
  • Dabbling:
    • Running samples
    • How-tos/Walkthroughs
    • Concepts
    • Practitioner Blog Posts
  • Starting building:
    • Concepts
    • API docs
    • Practitioner Blog Posts
  • The trough of despair and bugs:
    • API docs
    • Community/Support
    • Practitioner Blog Posts
  • Refinement & Completion:
    • API docs
    • Practitioner Blog Posts
  • Sharing:
    • Community: Here especially you will want to give senior users of your API a chance to share what they know. It can be through social media. It can be a chance for them to publish their own case study. But there has to be a reward (no matter how small) at the end of the journey. The easiest way is giving them a chance to blog on the portals blog.

Mostly a Science

The good news is that building a developer portal is mostly a science, with the exception of promotional material and running samples. But it does require a lot of effort. That is why we offer turnkey developer portal creation services so that organizations that need a credible and quality destination for developers (but do not sell to them directly) are not left with a developer portal which is more of a risk than a benefit.


Chris Riley (@HoardingInfo) is a technologist who has spent 12 years helping organizations transition from traditional development practices to a modern set of culture, processes and tooling. In addition to being a research analyst, he is an O’Reilly author, regular speaker, and subject matter expert in the areas of DevOps strategy and culture. Chris believes the biggest challenges faced in the tech market are not tools, but rather people and planning.

Would you like to share your thoughts?

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Subscribe to the Fixate IO Blog Highlights, Amplify

Keep up with the latest Fixate IO blog posts about influencer content marketing for B2B and increasing share of voice.  Sign up here: