When it comes to strategic decision making with regards to a developer portal, there are 3 dimensions that you can use to ascertain at what level of maturity you should operate: Operational maturity, Developer eXperience, and Business alignment. In this article we identify how 3 trends in 2020 align with these dimensions.
This article is based on our webinar “3 New Exciting Devportal Trends in 2020”.
Sign up for our devportal newsletter or check out our webinars page to find out about our latest webinars!
Developer Portal Maturity Model
We bring you 3 trends and how they relate to the developer portal maturity model
- Prose like prose as part of operational maturity
- Democratizing Developer eXperience
- Devportal microsites for business alignment
To understand why these three trends are important, we first need to introduce the dimensions of our developer portal maturity model.
Three dimensions that we see for gauging the maturity of a developer portal:
Operational maturity
- How easy is it for people to do their job within your developer portal?
- How easy is it for authors to contribute to the content on your developer portal?
- Have you created a system to address the needs of both your consumers and producers?
Developer eXperience
- How easy is it for people to use your APIs?
- Is friction being reduced and trust being improved?
Business alignment
- How do you go beyond your APIs just being technology?
- How do you go above one-size-fits-all portals so that there is value for different audiences?
- Is the devportal a technology solution or part of your business strategy?
- Have you adapted your devportal to your business needs or is your need for just a flat list of APIs?
Prose like Prose as part of Operational Maturity is back!
One of the failure states we see when teams build developer portals, is when they pick one authoring experience and make everyone follow that authoring experience.
For example with a highly technical team, there is a tendency to jump in with open source software and start building a static site generator site with an authoring experience that is highly geared towards developers who would like to use CI/CD and an endpoint.
In contrast, if it was the business makers who are deciding how the developer portal will be built, they will start in a content management system where there is more focus on making it easier for people to log in and easily iterate on content. So that marketing and business folks can tune the message without relying on developers.
If you work with technical writers, they will use CI/CD but with a repository where a few select people know how the content is structured and put together and then pushed to the developer portal.
From talking to many teams, you end up with a tunnel situation when working in isolation. You create a tool chain focused on one group (either developers, business folks, or technical writers) and all the other contributors have to adjust to this one tool chain.
Tom Johnson’s article titled Treat code like code and prose like code encapsulates this tunnel situation. While working with subject matter experts, he realized that people no longer contributed to the documentation although he was jumping through these docs-as-code hoops to collaborate. He asks: How do I get better feedback? He concludes that Docs as code was perhaps too ambitious and favors the more pragmatic rationale to go where your audience/authors are.
Operational maturity is about how the portal addresses the needs of its developers (CI/CD), business authors (CMS), and technical writers (Repository).
Questions to ask are:
- Do you have a way for developers to submit documentation without them having to access the developer portal?
- Can they submit an openAPI spec file and get it published?
- Do your business authors have the ability to add content without having to learn some special tool? E.g. can they log in and just add details to an easily interface
- Do you have some way of helping technical writers if they need to bulk upload releases?
Without a driver, even the best car won’t get you anywhere. Without people doing the actual writing, you can have the best technology but it won’t do any good. One of the hardest things to do, that we see with customers, is to actually fill your developer portal with content and for all the necessary documentation to be produced.
In the same way, you can have the right tool but if you cannot commit to the work necessary to use it towards the target outcome, you only have a fancy unused tool.
A crucial aspect of operational maturity is to give the authors of your developer portal content writing tools that they will want to use:
- Developers => Submit reference documentation through an endpoint. This could be enabling CI/CD to automate documentation updates for existing APIs.
- Business authors => Can rapidly iterate on business documentation like landing pages through a content management system (CMS).
- Technical writers => Enable centralized authoring of interconnected pieces of documentation that help to explain how APIs are used together, through a file-based authoring model or repository.
The take home here is not to build a tyrannical toolchain that is going to force your people to jump through hoops. Build a toolchain that is right for your people within the level of possibilities.
Democratizing Developer eXperience is necessary
How do we make it possible for regular people to use APIs and the API infrastructure, this information highway? How do we build the trust for your APIs?
KBC is a Belgian Insurance and banking company with locations spanning Ireland, Czechoslovakia and Hungary. They didn’t want just APIs on their developer portal, they wanted business solutions on their developer portal.
They have a QR code generator on their developer portal that a small business can use in their shop, brochures, or printed materials to trigger a loan- or an insurance sign up workflow. Why is this exciting? Small business owners (for example most bicycle stores are family businesses, not big chains) don’t have the money to pay for a developer to create a custom integration into an application. What this QR coded solution allows small business owners to do is to offer an automated integration to banking without any coding at all that will still trigger an experience and bring KBC solutions into their service offering.
The ultimate best developer experience is when one does not have to do any development at all. Even for software developers who are going to use your technology stack. It’s always better to have an SDK than an API. It’s better to have an app than an SDK or an API. Find out what people are trying to do with your APIs and make that happen as soon as possible given your ROI for a bigger share in your market. By turning your API portal into a business solution portal to show how you can integrate with a solution turns your API platform from something abstract and tech oriented into something practical and actionable where everyone can understand what they can do with it.
Katherine Van Gijsel, business manager at KBC, summarizes it as having a developer portal to address the needs of both software developers and business developers (The Present & Future of Banking APIs - Part 4, API Resilience Podcast). A portal where a business developer does not need to be a software engineer.
We are –mistakenly– treating developers as unicorns. For marketing purposes, messages on technology are dumbed down to such an extent that it becomes manipulative, and this is the messaging that developers don’t like. Software developers were stereotyped as a special night time dungeons-and-dragons playing populus who feed on beer and hackathons.
Instead, we could think of developers as pioneers. People who are looking for opportunities and ways to interact with businesses. Pioneers who build new bridges for technology and businesses to adapt and grow. To support pioneers we need to make sure that they have the right gear and tools.
“People don’t look for APIs they look for abilities “ Mehdi Medjaoui, APIdays (Key Elements of the API Mindset, API Resilience Podcast)
The value of APIs is not how you can do an integration, it is what you can do with it.
What can you do with an API? What are the affordances of an API? Identify and document affordances so that regular people can recognize the potential of your APIs.
What are the affordances that an API gives you and how can you discover new affordances?
KBC is using a solution that helps us go to digital proximity from physical proximity. There’s no fancy interface for doing coding work. They are not trying to replicate the developer experience. Instead they created a business developer experience that fits their unique needs.
Devportal microsites for business alignment are happening
How do you make sure your devportal is not just a technology but also something that solves a business function?
“In a single portal, there should be different sections for different audiences (like in a toolbox).” - Matthias Buescher, Deutsche Bank (The Present & Future of Banking APIs - Part 3, API Resilience Podcast)
Aligns with Business alignments - how will you go beyond your devportal as a tech solution? How do you get senior management excited about your devportal beyond it helping your developers? How can you get senior management to see this tool as a primary business solution that is helping you to execute business strategies? We need to adjust developer portals to the requirements and the goals we are trying to achieve.
In sufficiently large organizations it is better to have a federation of toolboxes that can be adapted to local needs. Any person trying to do a certain job should be able find the necessary tools in a concentrated place instead of having to go to many different places to find what they need.
How can developer portals further meet their business alignment needs? Can a developer portal be self-organizing?
Six Types of devportals
There are different types of developer portals. As we develop the idea of an interface economy we at Pronovix started to shift from the original idea of customer, partner, internal, & industry devportal types to expand instead to these six types of developer portals.
- API Marketplace - discoverability of a developer portal
- Ecosystem devportal - enables an ecosystem to self-service digital connections
- Platform developer portals - built to simplify a very specific and complex task
- Apps/Integrations portals - focus on what your audience needs to accomplish
- Market edge portals - cater to specific markets, localize interfaces
- Procurement portals - automate procurement and have vendors connect with you
Read more about the six types of devportals.
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 you can get better.
