How to build a developer portal that developers will adore
Length:
6 min
Published:
April 23, 2021
A developer portal is where developers find everything they need to implement your product or service. A well-designed one makes their job easier. A bad one slows them down. And the clearer and more popular your portal is, the better it is for your business. Developers are a demanding audience, but a friendly product wins them over.
How do you recognize a good developer portal?
Not sure what your planned portal should look like, or how the current one holds up? Look at it as a user would and judge a few key indicators honestly. Better yet, ask the developers themselves how it feels to work with it. Watch three things: business value, UX, and information structure. These questions will help you assess it accurately.
- Does the portal explain the benefits of the solution?
- How fast is onboarding? Can a user see the materials without registering?
- How does the portal look and behave? Is it clear? Does the user know where to start and how to reach their goal?
- Is there a testing environment? Is its data close to production data?
- Is it easy to find your way around? Does the structure make sense?
- Does the user get the right information, including pitfalls and specifics, at the right time and place?
How do you build a good developer portal from scratch?
At DX Heroes, we have all done development ourselves, so we know from experience what a developer portal needs to work well. Before we build, we answer four questions.
1. What is the business goal of the portal?
Beyond its information value, should it also work as a business channel that brings in leads?
2. Who is the end user?
Is it only a developer? Or also other roles, such as an analyst or a product manager? What is the least technical part of the audience?
3. Where does the business website end and the portal begin?
How do the two channels connect, and where is the handover between them?
4. What is the budget?
The size of the budget shapes the scope and the features. A small budget, for example, leaves no room for a sandbox.
Now we have the key information. What's next?
1. Define the tech stack
For us it is usually React or Next.js, plus an integration on the client's backend.
2. Analyze and design the structure
Lay out the portal so the pages and information follow each other in a logical order.
3. Decide where the instructions go
Identify what the user needs to learn and when, then prepare the instructions for the right moment.
4. Write the landing page copy
The text has to be clear and resonate with the target group.
5. Tune the API reference
Explain the parameters and attributes clearly. Where it helps, let users try the API out, for example with cURL.
6. Create the UI
Prototype from the materials you prepared, with all the elements in place.
How do you fix an existing developer portal?
Already have a portal, but it does not meet your developers' needs? Then adjust what you have. Start with three questions.
1. What is the business goal of the portal?
Beyond its information value, should it also work as a business channel that brings in leads?
2. Who is the end user?
Is it only a developer? Or also other roles, such as an analyst or a product manager? What is the least technical part of the audience?
3. What is the budget?
The size of the budget shapes the scope and the features. A small budget, for example, leaves no room for a sandbox.
And what's next when you're fixing it?
1. Define the tech stack
Decide with the client whether to reuse the existing texts in a new solution, or to evolve the current tech stack.
2. Review and adjust the structure
Check whether the pages and information still follow each other, and fix the structure where they don't.
3. Fill in and update the instructions
Add the instructions that are missing and update the old ones, so users learn what they need in time.
4. Edit the landing page copy (if there is one)
The text has to be clear and resonate with the target group.
5. Tune the API reference
Explain the parameters and attributes clearly. Where it helps, let users try the API out, for example with cURL.
6. Create the UI
Prototype from the materials you prepared, with all the elements in place.
Ready to improve your developer portal?
Want to find out how your portal is doing, or get advice on building a brand-new one? Get in touch with us and we will work out how to help. We will recommend what the portal should look like and how it should behave, and we will help you build it.
You might also be interested in:
Want to stay one step ahead?
Don't miss our best insights. No spam, just practical analyses, invitations to exclusive events, and podcast summaries delivered straight to your inbox.