“Reference docs do not constitute developer portals.”

This was the crux of a talk given by Nordic APIs veteran and Pronovix CEO Kristof Van Tomme at our 2017 Platform Summit. His opinion is that developer portals should function as self-service hubs for APIs, allowing developers to access APIs without having to wait around for access keys or any additional information.

Sounds simple enough on the face of it, but it doesn’t always work that way in practice; many API developers don’t offer a portal for their users and some fail to offer the appropriate information and resources to make using their API easy. So why is that the case?

One major problem is that many organizations don’t know what to include in a developer portal due to a lack of experience. This is especially true for traditionally brick and mortar institutions like logistics, airlines, banks, packaging, and insurance companies, who are opening up API partner integrations for the first time.

“…many of these traditional industries are weak at creating great developer experiences.” – ProgrammableWeb

Another prevalent issue is the fact that some companies don’t think they need a developer portal. This can be due to many reasons: Maybe their API is already being used, or perhaps they don’t see a problem with manually approving requests to use their API.

In this post we’ll be looking at how useful a good developer portal can be for streamlining access to your API, as well as how failing to provide the appropriate documentation can seriously damage the experience of integrating with it.

Trust

Kristof’s first point is that a developer portal is more than just an interface for your API strategy; it plays a key role as a signal of trust. A thorough and up-to-date developer portal says that “you can trust us, we’re not going to disappear. You don’t need to be afraid to spend effort and energy integrating with our API.”

He jokes that APIs should have developer portals for the same reason that banks still have big fancy buildings – because they build trust. Whether or not you actually trust your bank is a whole different issue, but you certainly wouldn’t trust a bank that’s headquartered in some back alley in a rundown part of town. Similarly, for online bank extensions, great developer portals are a critical part of open banking initiatives that must build trust with FinTechs.

In other words, “if it doesn’t have the right content, people won’t trust you.” In this respect, developer portals have a lot in common with a certain type of “features and benefits” sites targeted at consumers.

Take Shopify’s POS site, for example: the site presents the service’s 3 key selling points, 6 features, a simple breakdown of plans available and a testimonial. And, of course, a picture of a happy customer. Compare this with FreeAgent’s features page – 9 features and selling points, a testimonial panel and a link to a pricing page featuring a very similar plan breakdown.

Although the order and the exact numbers might differ, you’ll see that same format all over the web. Designers, copywriters and A/B testers have spent countless hours honing the perfect formula for the right content, i.e. that which will build trust.

Troubleshooting

So what exactly IS the right content? In the context of developer portals, it would appear to be content that delves into the technical ins and outs of the API in question. In other words, content that deals with troubleshooting.

In his talk Kristof outlines eight key features that most successful developer portals have, with those in bold being “must have”s:

• Reference docs
• Fast API key provisioning
• SDKs (automatically generated, but with some manual interaction where required)
• Landing pages
• Tutorials
• Guides to specific problems, including use cases
• Conceptual documents explaining difficult/counterintuitive terms
• Blogs

Incidentally, he points out that the last item on that list is optional: “If you don’t have people who are going to write on your blog, don’t include one; an empty blog is worse than no blog.”

You’ll notice that of the above, at least six deal with the experience of actually using your API, with blogs, landing pages and provisioning being potential exceptions. The latter provides the access itself and the first two typically deal with more contextual subject matter, such as case studies or statistics relating to the API. Pronovix also lists 11 questions that a developer portal MVP must answer here.

In other words, much of the content on a good developer portal should be designed to address potential issues a user might have as they encounter them. That means that you’ll be reducing support requests relating to your API, which is particularly key if you don’t have support team members dedicated to API-related queries (who may lack the specialist knowledge to answer them appropriately).

Communication

Kristof refers to the developer portal as a “communication nexus,” which is really just a fancy way of saying that it should bridge the gap between people who understand what the API does and those who don’t.

Kristof describes developer portals as a “communication nexus”

In the context of the above slide, for example, it’s likely that developers, evangelists and tech writers will be interfacing with sales, support and marketing to ensure that everyone in the organization understands the value of the API.

Kristof breaks down the API ecosystem into Industry, Customer, Partner, and Internal. While the above covers the Internal aspect of the API ecosystem, public APIs must involve stakeholders for external communication channels as well.

“A sign of a mature team is having tech writers and developer evangelists,” suggests Kristof. He’s certainly right in that these people, along with sales, support, and marketing, will typically be the forward faces that build relationships to spark API adoption.

Final Thoughts

We’ve seen above that there’s much more to quality developer experience than just uploading a few pages of technical documentation. While it’s true that a good developer portal can’t save a bad application, it’s definitely true that poor developer experience can derail the use of a great API.

With tools and services like Apigee Edge and services like Kristof’s own Pronovix, who build custom-fit developer portals, on the market it’s difficult to imagine anything supplanting the developer portal. Then again, it’s difficult to imagine a time when landing pages didn’t always stick to the “features, benefits, plans, testimonial” recipe too.

A big reason to spend some time working on your developer portal, from an organizational standpoint anyway, is summed up neatly here:

“Having the capacity to analyze engagement metrics from a developer portal…can provide strategic insights for a Developer Evangelist and Product Manager when deciding how to prioritize future spending on developer community resources.”

In other words, if you’re serious about your API then it’s time to get serious about your developer portal as well. It could very well end up shaping where your API goes next.