When you build a developer center or developer portal, you’ve got tough customers. They’re developers, after all. They either know precisely what they want, in which case they will demand that you deliver exactly what you advertise. Or they don’t know what they want at all, in which case you have to educate them in the most painless way possible, and make onboarding easy and fun.

For our purposes, a developer center consists of all the programmatic access and supporting tools and documentation that allow developers to build applications based on your stuff. (‘Stuff’ is a technical term.)

When you talk about developer needs, where do you start? We’ll divide our requirements gathering into two parts: 

• Who are your users
• What do they need to accomplish

Who are your developer center users?

Private | Public | Partner. In a private developer center, you can consider that your developers are in-house. Maybe everything is behind the firewall. Every developer is an employee with 2-factor authentication. So there may be some things you don’t need, like onboarding processes where you validate a phone number and credit card for example. Also, you might rely on company communications to transfer information between developers, in basically a flat knowledge hierarchy.

In a partner or public developer center, you should be metering usage for the purpose of ensuring fair access, and sometimes billing for it. Rate limiting also comes into play, for the purpose of protecting your infrastructure (and ensuring access for all). If you’re a public platform with an API, then your API is part of your product. 

Languages, Platforms and Preferences. You should have a good idea what the platforms and preferences are of your users. If your audience is React and your code samples all look Angular, then you’ll suffer at least a little slowdown in getting them on board.

Hidden in the ‘preferences’ part is a key to the level of sophistication. While you never want to talk down to users, you can be sure that the user of your php SDK  will have on average a few less years of experience than the user of your Java SDK.

What do your developer center users need to accomplish?

Onboarding. Ask any developer, and they’ll tell you that they don’t expect to get an API key without providing anything in return. This general process is called onboarding, usually you want to establish things like:

• Who should we talk to about the way this application is using our API
• Who and how should we bill for usage
• Any information about profile of usage that will help us provide better service

And while meeting these requirements, you should be sensitive to

• time required: rule of thumb is that 3 minutes should put you in a sandbox
• expertise required: if I can run a python script, I can get the example working (for example)
• administrative hurdles to clear (don’t require a credit card if you don’t have to)

Understanding. The standard developer center has you up and running with your own ‘Hello, World’ in just a few minutes. This can be accomplished by providing SDKs and sample code in the languages and environments that your developers favor. Don’t make them leave the environment where they know what’s going on, and they’ll have much more confidence that they can use your stuff.

But understanding goes further than getting an example running. It involves digging into the docs and finding out whether your platform can support their specific use case. Sure, they know they can create an order–but until they dig in, they don’t know whether they can create custom properties per order item. So–make it easy to parse the docs at a high level and also at a deeper level.

Getting answers. Kicking the tires always involves speaking to the community that uses a platform, or at least lurking there. Developers want to find out whether people have questions similar to theirs, and be satisfied with the answers they see. 

Going operational. Nothing is more frustrating than writing a bunch of code to conform to an API, and then finding out that you have to apply and wait a week or more to go to production. Interfaces support developers to know how their application is using the API, and there are likely additional APIs for handling exceptions, monitoring service availability, getting redirected to alternate endpoints, etc.

Being sold. We’re not talking about plaid blazers and strong handshakes. We’re talking about feeling like you made the right decision. Developers need to be sold on the solution they’re using, and ‘my CTO said so’ doesn’t go nearly as far as you think. Clear documentation, onboarding that works the first time, good customer service (if they ever encounter it), and a strong community all contribute to selling. But it also helps to be able to see clear comparisons to the competition. Many developers are only comfortable going with a platform when they are convinced that they know its biggest weaknesses. So be forthright with your comparisons, and don’t try to muddy the water. 

Developer center feature list

Once you know who your users are, and what they need to do, you can start to develop a feature list. That list should be understood in terms of the goals your users have, not strictly in terms of the features themselves. So here is Lab Zero's Top Ten list of features for a Developer Center.

1. API docs and catalog. Table stakes for understanding how your platform works, the docs and manuals should be up-to-date and match the version of the API that the user is on. A catalog of function or procedure calls should be hierarchical (in a way that makes sense and is easy to navigate). API docs are meant to be randomly accessed whenever you need to know a specific answer to a question.

2. Guides. Guides are one step up from the raw API docs. A guide might help me to accomplish a specific business objective, and include business domain knowledge about that objective. Guides are meant to be more approachable than raw docs, and lay things out in an order that they can be read from the beginning til the end.

3. API keys. Getting an API key can be a *huge* feature, and is typically broken up into many other features that overlap with onboarding, account registration, billing information, etc.

4. Dev sandbox. A sandbox is a place to play with an API without breaking anything. Some APIs may not need a sandbox. A translation API, for example, is read-only, and so you can ask for translations all day in dev or production and it’s the same thing. But scheduling parcel pickups from local couriers is definitely something you want a sandbox for. (You wouldn’t want angry couriers waiting on your doorstep every time you did integration testing, would you?)

5. SDKs and sample code. SDKs typically bridge the gap between the native access methods of your platform and the developer’s development and execution environment. For example, requests to an API may be RESTful requests issued via HTTP. But developers don’t want to build a User-Agent just to send and receive queries to the system. They want to send queries and get responses from within their application. You make this possible for them by building an SDK, or by hosting an SDK built and donated by the community. The SDK uses data structures and idioms native to the developer’s language of choice to access your platform. It’s transparent to them this way, and saves them a lot of time and effort.

6. Postman collections. Most API docs are really hard to read. They include arguments of infinite variety, and never seem to be interpretable at a glance. An example of an API call is a perfect solution for this. And postman collections are collections of ‘canned’ API calls that have a predictable response, and that help at the same time to illustrate the utility of a call.

7. Realistic sandbox data. We’ve all seen it: a user database that contains Abraham Lincoln, Mickey Mouse and Harold Throckmorton. Realistic sandbox data is much more helpful to developers, because it shows them the types of problems they will encounter when they go to production: the transactions with negative values; people with three first names; registrations that happen on February 29th.

8. Uptime and incident dashboard. When (inevitably) there is a boo-boo, you want to be able to quickly eliminate the possibility that your platform provider is the cause of the error. Being able to check the platform status for the time of the error can help you adjust the Arrow of Blame, and spend your troubleshooting resources more wisely.

9. Community. That’s a big word. What it boils down to is having a place where developers can help each other get what they want out of the platform. You might staff your email support 8am-7pm, but seriously there is lot of work getting done outside those times. And a lot of people who understand each others’ needs better than your team will.

10. Single Sign-on. If your developer center is linked to a customer-facing website (that you can also use as a human), you might want to make it possible for users to log into the developer center or the customer portal with the same login. It’s a feature that mature companies provide (like Amazon), but it’s getting to be table stakes for startups, too.

With a feature list, you can look at off-the-shelf solutions, compare those to your vision for what you need, and make a sensible Buy vs Build decision to get your developer center off the ground.

But that’s not all!

A few other important considerations have popped up in our discovery of requirements for dev centers.

How is the business website connected to the developer portal? As we said before, if your developer center is public, then it’s part of your product. As such, it’s never as simple as putting a ‘For Developers’ link in the footer of your business website that links to the portal. More and more, developers are part of the business team making a decision about partner platforms, and they are weighing the costs and benefits of the service you provide. Integrations at the account management level, content management, pricing might need to be discoverable in either place. 

What does a Build vs Buy decision look like? Following good product discovery, we're gathering requirements and talking to users as a big part of our process. But you can't ignore what's sitting right there on the shelf. Offerings like Backstage have really democratized the build process for developer centers. And products like Stoplight and Istio (just to name a few) are raising the bar for enterprise deployments right on down to tech startups. Look for our candid product evaluations in a future post.

Thinking about building a developer portal? We love that. Maybe we should talk?