What is a DevPortal?
According to Provonix, a primary sponsor of the DevPortal Awards, the definition of a developer portal is as follows:
“A developer portal – often shortened to DevPortal – is the interface between a set of APIs, SDKs, or other interactive digital tools and their various stakeholders.”
Said more plainly, developer portals are websites that provide interfaces for all services and solutions offered by a company. They are a resource for many kinds of stakeholders, not just developers.
A key difference between a normal website and a DevPortal is that normal websites contain static content while DevPortals contain dynamic content that is constantly being updated.
Developer portals, unlike wikis, are external while also acting as a resource for internal stakeholders. Since wikis are internal, they are often neglected and become out of date as priorities shift away from the documentation. Since developer portals are external, their maintenance is often a higher priority than internal wikis.
Surveys have stressed the importance of high-quality developer documentation. A survey in SmartBear’s The State of API 2019 Report ranked “Accurate and Detailed documentation” third place for the top characteristics of an API. DevPortals are the primary way SaaS companies share documentation.
There is also a blurry relationship between DevPortals and marketing websites. Sometimes an enterprise will have a marketing website that links to its DevPortal. Other companies, like SaaS-only companies, will have DevPortals and no dedicated marketing website.
What is the significance of a DevPortal?
So, why should a company invest time and money into enhancing its DevPortal? A good developer portal conveys the value of a platform and its services. It describes how it solves specific business challenges without using marketing/advertising hyperbole.
While API documentation is often associated with developer portals, a DevPortal is not just a place where developers access their API reference documentation. The DevPortal should allow all business stakeholders (technical or non-technical) to learn about and experience a platform.
In the next section, we will explore these characteristics.
What makes a good DevPortal?
The following are characteristics of an effective DevPortal.
Unifies solutions
While API documentation is an important aspect of a DevPortal, it is not the be-all and end-all. Developer portals ideally act as a central resource for all interfaces to a company’s products and services. They may not be limited to just APIs / services. Other interfaces include GUIs, no-code interfaces, and low-code interfaces like widgets for users without access to developer resources.
While REST APIs are a focus of developer portals, other kinds of APIs can be documented such as Internet of Things (IoT) APIs, voice assistant APIs, GraphQL APIs, or native library APIs. Oftentimes a company will have a range of services, not just a REST API. It is possible to see dozens of APIs of different types documented on a DevPortal. Other technical solutions made available on DevPortals besides APIs are client libraries or SDKs. Sometimes a DevPortal can also showcase solutions built by developers
Clear business model
The user should be able to understand the platform industry and a broad overview of the services it offers. Solutions should be categorized by area or specific business challenges they solve. The user should be able to develop a mental map of all solutions on offer and how they fit together in a unified platform.
How services relate to each other in the bigger context can be communicated through text, visual graphics, or the structure of the developer portal itself.
Up-front pricing
The customer should understand a platform’s pricing model very early on. The pricing structure should communicate how it solves particular problems and the differences between the pricing plans.
The DevPortal should answer questions like:
- How are the API products monetized (direct vs. indirect)?
- What are the differences between the available pricing plans? Are there plans for pay-as-you-go, self-service, or freemium?
- Are they any rate limiting restriction per pricing plan?
Pricing plans relate to the onboarding process because users are often allowed a limited number of features before they must pay. Transparent pricing facilitates the transition from a potential customer to an actual customer.
Content “layering”
Layered architecture is a concept borrowed from software development that can be applied to content organization.
Here is an example of how a DevPortal can be layered:
- The top layer of a developer portal would be the landing page the user understands the business model, an overview of services/solutions offered, and common use cases.
- The middle layer would be the solution categories that group solutions according to the business challenges they solve.
- The bottom layer would be the documentation for those solutions, including any getting-started tutorials and API references.
Of course, these are only examples. Other layers may be necessary depending on the business.
A layered architecture allows for consistency across solutions. The user learns what information to expect from each section.
Similar to the main landing page, each solution should have its landing page that communicates the value of the solution. A solution page provides quick access to the solution overview, use cases, onboarding details, getting started, and technical reference material.
Using a layered architecture that separates the different components of the platform allows for extensive use of linking. You can link to technical sections from business sections, and vice versa. For example, a business analyst that reads solution overviews may only want to view business information while also having the ability to learn more by clicking a link to the technical documentation. Linking also allows developers to jump to technical details rather than being stuck reading business material.
Consistent design
Design elements, when done correctly, go beyond aesthetics. Design elements promote usability and go together with the quality of the content. A well-designed developer portal has design elements that support the user journey as they discover, learn about, and interact with a platform.
An effective design reinforces the overall brand. A brand not only determines the aesthetic choice but also how the content is written. Documentation should be written using the same style and tone with consistency across all solutions.
Findability
How easily the user can discover the solution to their business challenge is the primary aim of a DevPortal. The process of finding information on a DevPortal should be frictionless.
The “findability” of information in the developer portal is determined by its structure and search/filtering capabilities. DevPortals should structure their documentation portals so users can easily see the range of solutions available. It should be easy to filter solutions by category to narrow down the list of possibilities and remove noise.
From within the API reference, you should be able to search and filter by resources, endpoints, parameters, and schemas.
Caters to non-technical users
SaaS companies also understand there are different ways to consume a technical product besides building an app that leverages a service from the ground up. For example, a platform may provide widgets you can easily add to your website with minimal coding. No-code or low-code solutions break down the barriers to who can experience the value of the technical product.
The best DevPortals have onboarding journeys for each competency level. For example, a technical user can build an app from scratch whereas a non-technical user can download a template to begin experimenting with.
Onboarding
The onboarding process is usually a user’s first experience using a solution. If there is friction in the onboarding process, a prospective customer may give up before fully demoing the API. After setting up your account and retrieving credentials, the Get Started section walks the user through an end-to-end process of interacting with the solution, such as an API.
API Reference
An API reference is a concise and detailed guide read by developers to understand an API. Effective API reference pages allow developers to quickly locate information for resources, endpoints, fields, or schemas using a combination of searching and filtering.
A try-it-out feature provides a hands-on way of interacting with an API. The most advanced DevPortals automatically populate try-it-out widgets with a user’s credentials based on their account details.
Community
Community is often first-level support for troubleshooting issues. Many dev portals have community pages. Some companies use tools like Discord channels or public Slack channels to host discussions under different categories.
If a user can find an answer by posting a question to a message board, they do not need to contact support. If a company is involved in the community, it can log the issue as either a bug or documentation improvement.
Communities can go beyond just discussion forums. They can lead to small meetings or large conferences that promote a platform.
Updates
Regularly posting updates as a platform evolves is a signal for reliability and trustworthiness. Release notes, statutes, and changelogs are all examples of supplemental documentation that keep the user informed of the latest changes
DevPortal Best Practices
There are many steps to building a DevPortal before any line of code is written. Assuming the business model is solid, developer experience (DX) design should be conducted to align all aspects of the portal to provide the best experience to users.
Clarify business model
The structure of the DevPortal should reflect the structure of the business and its solutions. The user will be lost if a DevPortal does not communicate the business structure well.
Keeping the portal up-to-date requires collaboration across the organization and will not succeed by relying on one team. All teams are responsible for keeping their domain up-to-date and responsive to feedback.
Conduct Developer Experience (DX) design
Developer portals are closely related to the concept of Developer experience (DX). Unlike normal User Experience design, DX is tailored to developers who use technical products often without a GUI like APIs, client libraries, or SDKs. Since there are no user interfaces, documentation must tell the developer how to interface with the product. Documentation to a large extent plays an important role in how a developer or other business stakeholder “experiences” a technical product.
In the same way, companies hire UX designers, they should hire DX designers to craft the experience of developers using the DevPortal. A DX “strategist” is a central role to manage the lifecycle of the developer portal. The DX strategist oversees changes to processes, standards, and tooling that flow out to individual solutions teams. This strategist ensures the design, aesthetics, structure, and content work together to create a pleasing experience for the developer.
The strategist creates the personas of the people visiting the portal and crafts user journeys to meet their needs. For example, there would ideally be separate onboarding user journeys for technical users and non-technical users.
Structure the portal
When establishing the information architecture, you must determine which information is required across all solutions. For example, each solution requires onboarding, use cases, and API reference in a particular order. If documentation is uniform across solutions, the DevPortal user knows what to expect.
A layered architecture, coupled with linking, will make navigating from the top layer (business details) to the bottom layer (technical details) easier, and vice versa.
Establish governance program
Many times, each solution is managed by a separate team. To provide a consistent experience across the portal, standards must be established that promote the consistent organization of content and writing guidelines.
Establishing a governance program requires collaboration to develop standards as well as buy-in from the separate business units to fully complete the program. Each team should be responsible for adhering to these standards and held accountable. A governance program should align language and tone, style and formatting, and organization of content from business material to API reference. Finally, a governance program should reinforce branding.
Reduce the learning curve through onboarding
After communicating the value of the business as a whole, the user should be immediately guided toward separate solution pages where they can try out APIs, services, client libraries, or SDKs. The front and center of these pages should be a link to onboarding procedures so they can experience the product as soon as possible.
For the Get Started tutorial, pick a simple use case that the user can follow to understand the solution from start to finish.
Properly document API reference
Are all the API components accurately documented? Is each resource documented? Are individual endpoints and schemas described fully? Does every field description state its purpose, the effect of chosen values, and interactions with other fields in the system? Are definitions for the same field standard across the spec? The content of the API reference should follow an API style guide that determines standards for all components of the API. Following a style guide ensures consistent and complete documentation across the API reference. Without accurate and detailed reference information, all the flashy features are useless.
Documenting technical reference information is often the first step to improving overall documentation because the technical information must be solid before writing tutorials.
Configure search / filtering
A DevPortal can have dozens of pages corresponding to separate solutions. Along with a clear site structure, having a robust search can improve discoverability so the user can find the solution that solves their particular business issue.
There should be an API Explorer where the user should be able to search and filter a list of solutions offered.
It is important to have a robust search in API reference docs. The search bar on an API reference should allow for a granular search of all components making up the API.
Establish community
From early on, you should think of ways to foster and grow a community around your business’s solutions. This is both a long-term strategy for support and also for the adoption of your products.
Other subtler forms of community are asking developers to sign up for newsletters that keep the communication line open.
Initiate a feedback loop
There should be many opportunities on a DevPortal for a user to provide feedback. For example, each API reference section provides a rating mechanism with the option to provide free-form feedback.
Another source of feedback is community. A community actively using a product that posts is a source of feedback without even having to ask for it.
Provide case studies and references
Case studies are convincing when they are coupled with testimonials of clients that use the product. Case studies can be common business challenges and how they are solved using a platform. A user may relate to a case study and immediately see how they can use the tool to accomplish a certain task or solve a problem that someone else experienced.
Regularly post updates and statuses
Regularly posting updates as a platform evolves is a signal for reliability and trustworthiness.
Top comments (0)