How do I know what to work on to improve my developer portal? What are the different aspects I should be thinking about? What should be my priorities? How can I increase value, from the first MVP all through to a mature established developer portal? How do I do all this, even when I don’t yet have a clear path to value for my company’s API program?
At this point in time, we have identified 3 independent dimensions that API teams can work on to improve the business value of their developer portal. To some extent developer portals can evolve from MVP to maturity along one of these dimensions while still lagging behind on the other two. For maximum business value, however, you will need to work on all three: your operational excellence, your Developer eXperience, and your business alignment.
All of these dimensions can be also aligned to a sliding scale as it is hard to clearly identify at what point you progress to the next stage of maturity. We illustrate 3 stages for this metaphoric sliding scale:
Devportal as a project: Your devportal is part of an API roll-out, a project team has been assigned to create an API documentation site to help promote your APIs. The bare minimum documentation has been created by the API developers and the API team lead has done their best to create a few business documentation pages. There is however no process or plan to update the documentation. There is no technical writer on the team who will iterate on the content to improve developer experience.
Devportal as a product: Your organization has made a decision to start an API program. And knows that a developer portal and its developer experience will be a key factor for the success of your API program. The API program team has people dedicated to the developer portal, and a technical writer (or somebody with that role) is working on the information architecture of the developer portal to iteratively improve developer experience. You are aware of the need for both business and technical documentation and have set up a process to enable people from around the organization to contribute.
Devportal as critical business infrastructure: Your organization has become a digital business that runs an intentional interface strategy. Your developer portal is a control center that helps your business to execute on its ecosystem, platform, and digital product strategies and that helps you to explore and test new interface opportunities. People from all parts of the organization collaborate with the devportal product team to iterate on business and technical content. Successful API product teams iterate on their parts of the developer portal, and the portal journeys that funnel key personas to the content they need along their downstream API journey.
The 1st Dimension: Operational Excellence
Does your developer portal work in synergy with all your authoring personas? Are there some (or everyone) who need to push through significant friction to be able to contribute to your developer portal?
Does your developer portal work in synergy with all your authoring personas? Are there some (or everyone) who need to push through significant friction to be able to contribute to your developer portal?
Your developer portal does not only serve API consumers, it also needs to work for the people who publish documentation about your APIs. On a typical developer portal, there are broadly speaking three types of authors that will need to get their content published:
Developers: Sometimes developers don’t like writing documentation. When these developers need to switch context to write, you might end up with even less documentation, by forcing developers to log into a CMS, or to follow a repository to make their changes. That is why we recommend that developer teams use a CI/CD process to submit reference documentation to the devportal (e.g. OAS files).
Business users: A developer portal is a business tool, even if it is different from traditional marketing websites. It is critical that product owners, marketing, sales and devrel stakeholders can adjust content on the devportal. Forcing business authors to edit content through a developer centric workflow adds unnecessary friction that can slow down or impede contributions (we’ve heard stories about teams where it takes months to publish an API, or where a devportal owner has become a single point of failure bottleneck). We believe that the CMS authoring interface for business personas in our developer portal can help.
Technical writers: Technical writers (at least in the role of editor) are essential for a mature API program, but are missing from most API teams. Until recently, we didn’t have a dedicated authoring or publishing experience for editors in our product, and we built custom APIs with existing authoring solutions.
It is an anti-pattern to force all three stakeholder groups to have their own authoring experience in the developer portal. While it can make sense for business audiences to author in the developer portal CMS — it helps them to integrate an API into the business vision and developer marketing framework— we recommend our customers to adjust a working toolchain to all authors’ needs and to the organization’s requirements. We see our developer portal solution as a publishing CMS and not a cure-all authoring interface.
For more on this topic see Operational maturity.
The 2nd Dimension: Developer eXperience (DX)
How well does your developer portal serve your API consumers? Have you removed as much friction as possible from the API journey? Have you incorporated trust signals to help them make their interface investment decisions?
In our blog articles, we have written a great deal on the subject of developer experience from developer portals. The maturity is reflected in terms of how far on your developer portal’s journey of meeting your DX needs.
The 3rd Dimension: Business Alignment
Is your developer portal an IT solution that helps you to execute on your API program, or have you worked on an interface strategy that complements your business, and that will help your company to adjust to and thrive in a complex and always changing market?
Goals you may include:
- Encourage cross-team collaboration, innovation, cooperation,
- Increased revenue from technology integrations.
- Increased adoption of your products both internally and externally.
- Better documentation of technology.
Developer Portal Maturity Model Do you agree with this? Where are you in this process? Schedule a call to discuss where you are and how we can help you get to where you want to be.
The DevPortal Awards
Since 2018 Pronovix has sponsored the annual DevPortal Awards. These awards were established to shine a light on the digital transformation that was taking place across various industries opting to create and promote their Rest-API products via developer portals. As the type of developer portal ranged from static site generators to full-on CMS driven enterprise portals, the first three years awarded 9 mostly developer experience categories for winning portals. In 2021, with the introduction of the developer portal maturity model, and a recognition for the innovation that was occurring in this space, new award categories were introduced. Further, the best overall developer portal, where all nominations are considered, was expanded to award not one but two awards based on the size of developer portal, Enterprise Small & Medium Enterprise (SME).
Awards for excellence in Developer Experience
- Best API reference documentation
- Best findability of products in a DevPortal
- Best visual design
- Best onboarding
- Best community spotlight and outreach
Awards for excellence in Operational Excellence
- Best accessible devportal
- Best use of analytics in a devportal
- Best international and localized devportal
- Best new DX innovation
Awards for excellence in Business Alignment
- Best served API Business Model
- Best use of monetization
- Best DevPortal for Citizen Developers (Low/No-code) (new in 2022)
- Best DevPortal beyond REST platforms (new in 2022)
- Internal DevPortal (Awarded in 2021)
We invite you to explore the past winners of these awards who have broken ground since 2018 for technology and innovation with their developer portals. For insight into how contenders were judged, we have published an interview with the Developer Portal Awards Jury of 2021.
Original published 2020-10-01
