Christoph Weber - An overview of devportal technologies and their (dis)advantages

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

Prebuilt:

• Cloud-hosted Devportal as a Service
• DevPortal built into API gateway

Custom built:

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.

CMS-based:

• 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

API-based:

• 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

CMS-based:

• 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

API-based:

• 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:

1. Frustration of a forced tool change
2. 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:

1. Duplication of content that already exists in publication-ready form. Things will inevitably diverge
2. 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.