Your developer portal is the home for your API or developer tool. It’s the center of your developer experience. And you may be ignoring many of its visitors, primarily because you can’t see them.
Like viewing this layout of paper plates, you can change what you see by altering your perspective. When you first look at the plates, they may appear upside-down or right-side-up. Look around at the other plates and if you’re willing to see them the other way, the image will appear to flip. But they were there all along. The only thing that flipped is your perspective.
You can do the same with the audience in your developer portal:
- Rethink your audience
- Find out what they want
- Make it easier for them to get it
The formula is simple, but it takes effort to implement. It all starts with reconsidering who is visiting your portal. Because it’s probably not a complete overlap with who you have in your mind.
Rethink Your Audience
To find your invisible audience, you need to be willing to adjust your eyes. That means thinking through who it might be, then seek out signals that they’re already interested.
- Technical depth: your audience may be more or less technical than you think
- Language/framework choices: your stack might not be their stack
- Self-identification: “developer” might not be the best label
As a former Zapier employee and the guy who wrote API’s Dirty Little Secret, it’s no surprise that I think there’s something to the low code movement. For every type of high code project, there’s a low code version—or several—waiting to be used by someone who doesn’t typically compile or deploy. From websites to mobile apps to SaaS integrations, there’s a whole lot that a motivated non-programmer can produce.
Perhaps the tools don’t have the customization that more technical users want. They are unlikely to be selected by engineers who need control of all aspects of their work. But that’s kind of the point. It’s a different audience. And it might be bigger and hungrier.
Even within developer groups, the portal often communicates a technical bias. For example, if you’re a cutting edge startup using Node and GraphQL, you may not notice the enterprise Java engineers looking for your SOAP API. And the reverse can be true, too.
And languages might not be the answer, or at least not enough. Alex Salazar, former CEO of identity startup Stormpath, credits their attention on frameworks with changing their business trajectory. It all started by offering a quickstart for Flask (a Python framework) in addition to vanilla Python. With that success, they oriented their entire portal around the developer’s framework, not just language. In early 2017, Stormpath was acquired by Okta.
Finally, looking for “developers” might not be the way your audience identifies. In recent years, I’ve noticed a move toward different names. Operators, creators, architects, system administrators, or some other term may better describe your audience, even if they’re technical.
In this classic awareness test video, it shows how easy it is to miss something you’re not looking for. When rethinking your audience, it’s important to think about who it might be, then look for signs that they’re visiting your portal.
Find Out What They Want
The well-tread customer development advice is that you should talk to your audience to find out what they want. I’ve done many hours of these calls and they’re hugely valuable. But you can get more out of them if you first take a look at what other signals might be suggesting.
You may have untapped data in your:
- Website analytics
- GitHub repositories
- Package managers and SDKs
These tools, and many more, already have signs about what your audience wants. At Zapier, the platform’s direction came from paying attention to cues from analytics. Like the awareness test, the message is subtle—until you know what to look for.
Before I joined Zapier, the team built a Command Line Interface for the platform based on customer feedback and company needs. It’s exactly what a developer would want, but very few clicked the link to try it out.
So, naturally we made it a button. When that still didn’t get the majority of the clicks, we made it the primary button. As you might guess, that didn’t help.
Even when we demoted the old version to a link and called it legacy (I may have embellished these prototypes), most visitors found their way to the link. In retrospect, the message was loud and clear: we are not developers, so don’t give us developer tools.
With similar data about your portal and other related tools, you can get an idea of what your audience wants. Then round it out directly from users. In addition to formal interviews, you can send short emails, embed feedback forms in docs, and attach quickie surveys at important points.
Not all of what you learn will be actionable inside the portal. Developer portal darling Twilio is building low-code tools on top of its APIs, likely based on feedback from an audience that doesn’t respond to “developer.” Those changes go way beyond portal updates, but many will.
Once you learn who your invisible audience is and what they want, you can help them get it: either by updating products, or through content and features in your portal.
Make It Easier for Them to Get It
There is no such thing as a perfect developer portal. The best API companies keep improving, which means discovering audience and providing what they want is an ongoing process.
Yet, most portals have a lot of room for improvement. It’s easy to get bogged down on all the potential projects you could take on. As a first step, remember that nobody makes bad documentation on purpose. There are plenty of reasons it happens. Some are even reasonable.
To begin, make sure it’s easy to begin. The getting started guide is the most important piece of content. Make it discoverable and get to an early win quickly. Continue to look for where the guide trips up first time users and sand down the rough edges.
In fact, you can follow that same approach with everything in your portal. You may realize you need new SDKs and framework-specific guides. You’ll have use cases that you support with sample apps and corresponding tutorials. Everywhere you notice a snag that’s tripping up your audience, look for ways to remove it.
While it may seem obvious, remember that the hard part is that change in perspective. The invisible audience is already visiting your portal and you aren’t serving them right now. Discover who they are, find out what they want, and then help them be successful.