Quality API documentation is unquestionably the lifeblood of the developer experience. Most self-service tools require detailed tutorials, even for simple use. We know developer adoption drives the success of numerous APIs, so why not make their lives as easy as possible?

Kristof Van Tomme, co-Founder, and CEO of Pronovix, believes we can create user-friendly developer portals by following key best practices. These focus on improving onboarding, resource access, and overall project ease. We must also scale our documents effectively as our library of available APIs grows. This task can be quite daunting. Your technology’s biggest supporters deserve the best experiences you can provide.

Luckily, Kristof has given us three main solutions for scaling developer portals. We’ve summarized his recommendations below, based on the feedback he’s gathered from companies and developers.

1. Make Your Content Discoverable

Discoverability is commonly overlooked while scaling portals; however, making APIs discoverable is quite important for creating self-service products. Companies offer a growing number of services as they expand and create numerous APIs to grant third parties access to them. Many issues boil down to semantics; many APIs often have obscure names with little contextual value. Consequently, it’s difficult for outside developers to grasp which APIs serve which purposes.

Keyword searches are particularly useful when diving into unfamiliar territory. As developers and human beings, we like to track down items using terminology that logically resonates with us. Efficiency plummets when API titles consist of random alphanumeric sequences. This leaves developers in the dark. Portal creation is an exercise in UI/UX design – even though key information may only be a few clicks away, discovery can be shockingly difficult.

We can explore a short list of resources pretty quickly. However, it becomes exponentially more tedious to parse through hundreds of documents when search is unreliable. Library growth can accordingly become a developer’s worst nightmare. Proper metadata creation and placement are key, but your portal equally requires a clear organizational hierarchy.

Create an Organized Structure

Kristof says a layered content structure emerges from this approach. You’ll have your APIs packaged with crucial information – like OAS, Markdown, and JSON files. These JSON files will contain key metadata for searchability.

Kristof’s layered layout, which progressively leads developers to more granular information.

Generally, this API container layer (green, see above) is the lowest level of your documentation. The level immediately atop that foundation includes building block guides and instructional materials. These guides are accessed via landing pages, which ultimately stem from your developer portal’s main landing page. Moving through a well-organized portal is thus akin to navigating a website. You start broad and then narrow your focus.

He also praises DHL’s faceted approach, which displays all APIs at once while allowing filtering:

DHL provides developers with an uncluttered, easily-navigable interface.

Best of all, this layout emulates almost every product search page we encounter online. That familiarity is robust and innately gives users an idea of where to go. This combination of clarity and efficiency allows your developers to work smarter.

We can solve the problems of discoverability and findability with a little effort. However, this is the “easier” development gremlin to deal with. Content structure is one thing, but securing resources and funding is even more challenging.

2. Demonstrate Clear Business Value

Business owners often grapple with their bottom lines. Your developer portal conveys both how to use your APIs and what makes them valuable. This, in turn, draws developers into the fold – gradually legitimizing your services and promoting company success. Many product teams don’t realize how pivotal the developer experience is to earning revenue.

These developer portals are a continual investment. Time and money are needed to produce new content, and updating key systems takes effort. You may have, say, seven APIs in your library. Your content will evolve and multiply as these APIs gain added functionality. Any API changes must be reflected in your documentation as they occur. If your library expands, your portal will as well. This requires investment in various forms.

Many stakeholders will also contribute to your portal’s success. Not all included content will be technical. While it’s important to include the technical ins and outs, Kristof urges us to consider “business personas” as well. Your APIs may be dynamite, but as a product owner or marketer, you must convey why these APIs are suitable. This is why we should see value propositions intermingled with code snippets.

Portal Improvements Should be Proactive and Reactive

Van Tomme argues that your portal shouldn’t only be a product platform – it should be an affordance platform. Before we get there, we must consider how the enterprise is changing. Kristof argues that companies are more flexible and open-minded while they’re growing. These same companies become resistant to change as they mature.

That missing adaptivity is sorely needed while your business scales. Companies have to embrace complexity and systems thinking. When companies grow, they add services and tools to their repertoire. Technical teams must document these changes accordingly. If your existing developer portal can’t support this growth, it’s time for a revamp. Kristof asserts that our documentation portals must scale effectively alongside their respective businesses.

Complexity isn’t a bad thing. It relies on four things: interconnectedness, interdependence, diversity, and adaptivity. Van Tomme hypothesizes that developer portals can help drive complexity and value chains between pieces of information, businesses, and customers. These portals are tools that “can help you turn your company into a complex adaptive system (CAS).”

3. Consider Combining Your Backend with a GUI

Authoring approaches differ from one dev portal – or team – to the next. For example, content creators may favor a GUI-centric approach borrowed from content management systems (CMS). Others favor the repositories and static site generators (plus Git, Terminal, Bash, etc.). These vary greatly in terms of granularity and technical knowledge required. The best approach blends both CMS and “documents as code” into a single program, which Van Tomme finds beneficial.

What do these documents include in a coding environment? Developers may utilize Swagger.io, OpenAPI Specification (OAS), Markdown, and various attributes to create documentation. There are also data formats like JSON and YAML. Such tools give developers numerous ways to organize and publish content.

There’s a learning curve associated with these technologies, especially for non-technical folks. These authors will prefer a CMS. That flexibility allows you to involve multiple team members. Automated templates pull from CMS-generated content, determining which developers need to see which content based on role-based access control (RBAC) configurations.

In short, your developer portal should serve uniquely relevant content to each user. The CMS is also the perfect outlet for making content changes, which is where static tools falter.

Closing Thoughts

This may sound confusing, but the overall premise is fairly straightforward. Your developer portal helps foster the growth of a development community around your APIs. In order to provide great experiences to developers, your portal must evolve in response to new documentation, business, and a changing development climate. Developer portals will help your company stay relevant in the eyes of your customers.

Developer portals are often the unsung heroes of your company and APIs. They deserve care as if they’re a living-and-breathing organism. Developer experience is often overlooked; Van Tomme argues that fine-tuning these gold mines of information will pay immense dividends for all involved. This information, once shared, is essential to creating new marketplaces for your APIs.