To choose a tool appropriate to your needs is to understand what functions it will serve. This article identifies the key reasons why you would choose a static site generator (SSG) or a content management system (CMS) for constructing your devportal.
When to use a CMS for Developer Portals
You have been diligent and outlined your user personas and user stories. You have carefully curated the documentation you want to include and maintain to explain the business value of your APIs. You have even planned out and are ready to build a Developer Portal.
But how to build it? Should you use a CMS?
To this question the answer is three more questions:
- How many APIs do you have?
- How many people are managing them?
- What are you trying to do with your APIs?
If the answer to the first two questions is few and few. Then like a hammer compared to a sledge hammer, a Static Site Generator (SSG) will solve most of your requirements versus a Content Management System (CMS).
Static site generators are serverless and headless technology that do not rely on a database or plugins. Most of these are built on a JAM-stack (Javascript, APIs, Markdown). Using a static site generator will give you a fast load time, flexibility, no back-end, reliability, security, less maintenance and the lowest cost overall. Jekyll, Hexo, Gatsby, Hugo, and Next JS, are a few JAM-stack SSGs that can serve to build a good developer portal.
However, as your company grows beyond a startup phase and the number of people involved increases or your API product and support needs double - you may find yourself looking for more functionality and consistency with respect to your documentation and developer portal.
A Static Site Generator becomes limiting, more time consuming to maintain and no longer serves its original purpose due to inconsistencies introduced to content and structure. Should you have more than one technical writer or developer updating content, they have to coordinate so as not to overwrite each other’s changes. In addition, an internal list of APIs may now contain the title ‘__AAA_most_useful_API’ so as to be found at the top of the list.
We come back to the question of What are you trying to do with your APIs?
Is your developer portal an internal directory listing all of your company’s APIs with links to documentation? Is the purpose of your developer portal to provide APIs and documentation to external users who wish to harness the power of your APIs to innovate and expand on products and services you offer? Do you need people to be able to search your API listings to find and access what they need? Do you want to provide your API consumers with a sandbox, example code usage, access keys, and other supporting documentation? Are you just looking for a way to get cross-functioning teams to collaboratively provide documentation, marketing, and support for your API products?
If the answer to any of the above questions is ‘Yes’ or ‘Maybe’ or even a ‘Maybe, in time’, then a CMS (Content Management System) is what you need.
The benefits of using a CMS
To jump off the deep end, a CMS will allow for the publishing and management of between one and hundreds to thousands of pages. With a CMS you can allow a multitude of users to access the site via a log in, fill in forms, search, or participate in discussion forums. A CMS can reliably scale to your needs.
From a design perspective, CMSs come with some form of page builder to allow drag and drop ease with respect to how pages are laid out. A CMS provides some form of website authoring, collaboration, and administration tools.
Wordpress, Joomla, and Drupal are a few CMSs with varying strengths and weaknesses that can be used for building your developer portal. The choice of which to use comes down to the scale of your needs, resource constraints, your knowledge of the CMS, and finally the choice of whether you are building an in-house software solution, building and maintaining via a contracting agency, or licensing a SaaS.
Are you building a developer portal? Interested in a shortcut? As a devportal specialist, Pronovix has created developer portals for 40+ customers in the past 4 years. Talk with us to learn how our SaaS developer portal can accelerate and simplify your launch.
