It used to be only businesses that sold to developers needed to worry about having developer portals. Then, companies with an API or selling tech products found a need for developer portals. But now, unless you are only a brick-and mortar-retail shop, most businesses need a way to engage and work with developers. For those that do not directly sell to developers, building a portal doesn’t come naturally. This post includes some best practices for building a developer portal from the ground up.
Know Your Audience
Developers don’t fit the description of the typical customer. Developers use their time efficiently, approach almost everything with a critical eye, and expect a lot. This means you should make it easy for them to use your portal. The portal needs to cover all aspects of the developer journey (as listed below). Doing so will mitigate frustration.
The Developer Journey
The developer 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 becoming 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:
- Hears about the tech: From a peer or online techies, the developer discovers your API and is interested 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.
- Dabbles: The developer builds a “hello world” type application. The product likely isn’t a long-term application but is a good go/no-go to keep playing.
- Starts to build: After validating they can build a hello world application, the developer identifies 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 begins building their application, they hit a point where your project is a new favorite curse word. They find bugs within your API or their application, because they are trying to do something no one else has before. 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 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.
Keep in mind: each step of the developer journey is 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.
- Create a budget: For companies that don’t sell to developers, this can be rough. Because it does not directly relate to the bottom line, you often aren’t 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. As with practitioner content marketing, without a budget there really is no point in beginning.
- Taxonomy/Information architecture is important: To meet the expectations of the developer journey, the way in which you structure the content is just as important as the content itself. A predefined, yet flexible, information architecture is an important first step.
- Don’t assume their entry point: Portals should have a sufficient blend of documentation, use cases, and promotion. If it’s just documentation, 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. A blend of all three builds the developer’s enthusiasm and let’s them know how and where to spend it.
Portal Structure
Here are the key content components of all developer portals:
- Use cases: Promotional material on why the framework is used. You may have to tailor this to specific common examples, including verticals.
- 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 easily learn about concepts that are core to the tech.
- 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.
- 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.
- 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.
- 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.
- Community/Support: This is the aspect that many organizations see as a runaway train of effort and cost. If not structured with the appropriate guide rails, it can be. But, a supportive community helps developers move forward if they hit a wall.
Connecting Structure to the Developer Journey
All of the aforementioned components need to have relevant, timely, accurate, and consistent content. Here is how they align with the developer’s journey.
- Hears about the tech:
- Use cases
- Running samples
- Practitioner blog posts
- Dabbles:
- Running samples
- How-tos/Walkthroughs
- Concepts
- Practitioner blog posts
- Starts to build:
- Concepts
- API docs
- Practitioner blog posts
- The trough of despair and bugs:
- API docs
- Community/Support
- Practitioner blog posts
- Refinement and Completion:
- API docs
- Practitioner blog posts
- Sharing:
- Community: Here, especially, you want to give senior users of your API a chance to share what they know. This can be through social media, case studies, and more. But there has to be a reward (no matter how small) at the end of the journey. The easiest reward is giving them a chance to write for the portal’s blog.
Mostly a Science
The good news is: 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. Organizations, even if not selling directly to developers, need a credible and quality destination for developers. That way, you’re not left with a developer portal which is more of a risk than a benefit.
To learn more about Fixate’s developer portal creation services, contact us.
This post was originally published in April 2019 and updated in July 2022.