Devportal CMS? CI/CD? Docs as code? Why choose if you can have them all?
Can your internal stakeholders do what they need to do on your developer portal? Is the portal adjusted to their authoring needs, or do your developers, business stakeholders, and technical writers need to bend over backwards to be able to publish or change content?
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: Most developers don’t like writing documentation. When developers need to switch context to do so, you end up with even less documentation. Forcing developers to log into a CMS, or to follow a repository to make their changes. That is why, when to our clients we recommend that developer teams use a CI/CD process to submit reference documentation to the devportal (e.g. OAS files).
-
Business: A developer portal is a business tool, even if it is different from traditional marketing websites. That is why it is critical that product owners, marketing, sales and devrel stakeholders can adjust the content on your devportal. Forcing business authors to do so 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). That is why we have a CMS authoring interface for business personas in our developer portal.
-
Technical writers: Even if technical writers (at least in the role of editor) are essential for a mature API program, until today most API teams don’t have technical writers. That is why until recently we didn’t have a dedicated authoring or publishing experience for them in our product, instead we built custom integrations with existing authoring solutions. As the market matures we have seen more technical writer teams.
It is an anti-pattern to force all three stakeholder groups to have their authoring experience in the developer portal. While it can make sense for business audiences to author in the developer portal CMS, because it helps them to integrate an API into the business vision and developer marketing framework, we typically recommend our customers to adjust the toolchain to what is already working for your authors. We see our developer portal solution as a publishing CMS and not a cure-all authoring interface. This gives our customers more flexibility to adjust their toolchain to their organization’s requirements.
But what does this mean for the maturity of your developer portal? Just like the other two dimensions, operational maturity is also a sliding scale, and it is probably hard to clearly identify at what point you progress to the next stage of maturity. But for the model’s function we have separated operational maturity into the following 3 stages:
-
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.
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.
