How to choose from the various systems that can be used to build a Developer Portal?
”Meet your authors where they are” Alanda Orozco, C3.ai
The chosen platform will influence the authoring experience. If the contributors can use their preferred tools, the engagement will be improved on their part. It leads to better quality, consistency, and sustained success.
Basic types of Devportals
Cloud-hosted Devportal as a Service
DevPortal built into API gateway
If the client needs more than what a prebuilt version can offer.
CMS: Drupal or file-based CMS
JAM Stack: Decoupled frontend with CMS backend or static site builder
3 authoring experiences
The chosen platform influences the authoring experience.
Tight coupling between the content model and a UI
Publish directly in the same system
The author can build reusable components, arrange them, mix and build the exact documentation that the end-users need
Docs as Code:
Code repository or file-based CMS and some sort of CI/CD process to publish
The open API spec is built to expectations that all the pieces that are needed are there, else the build or merge will fail
Command line or endpoint as the interface
Have an already existing body of work
Ideally the user wants to minimize duplication
3 personas and their preferred authoring experience
Marketer: uses Office 365 and Adobe CS. Prefers CMS-based authoring tools, like WYSIWYG
Developer: uses IDE and git for version control. Prefers Docs as code
Tech writer: uses Office 365 and other tools, always with templates. API-based authoring works in this case, because the output is already highly structured and ready to go
The task at hand:
”Get the API documentation out efficiently in a consistent manner, and do it in a sustained fashion. The tools, the toolchains and the way to achieve it is secondary to this.”
Authoring experiences compared
SaaS: typically limited
Gateway: may be there, but typically limited
Drupal: native in the system and extensible
JAM stack + CMS: more technology in place, it is also more expensive, risk factor is high (things may break)
JAM static: no CMS-based authoring
Docs as Code:
SaaS: built in, published content goes right into the system
Gateway: once the API is built into the gateway, documentation will be in the devportal
Drupal: as an extensible framework, Docs as Code can be custom built to specifications
JAM + CMS: the framework can be extended to be able to do Docs-as-Code, but: more technology in place, therefore is is more expensive, and risk factor is higher
JAM static: native, because a static site builder is a code base
SaaS: not there at all
Gateway: not there natively, but it can be cobbled together
Drupal: possible, because the system is extensible
JAM + CMS: possible, but more technology in place, therefore is is more expensive, and risk factor is higher (things may break)
JAM static: can be built, minor integration is needed
What happens if the authoring experience is not taken into account?
No easy CMS-based authoring: marketing persona can’t play on their strengths. Two obstacles:
Frustration of a forced tool change
Stunted evangelism: Docs as Code or API-based authoring removes finetuned control over the layout
No API-based authoring: leaves out the tech writer’s existing, templated toolset. Two obstacles:
Duplication of content that already exists in publication-ready form. Things will inevitably diverge
Slows down publication: techwriter is already done, only needs to expose content
Meet the new human interface layer
If there are no differentiated and optimized authoring experiences, it can result in a new caste of system experts who are there only for content publication. It is a stumbling block when the team can’t use their preferred way of getting content into the system.
API First program is trying to go the other way and create automated, efficient flows.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.