It is really hard to chose the right technology to use to build your devportal. The various types of devportals support 3 authoring experiences: -CMS based authoring - tight coupling between the content model and a UI -docs as code - code repo, or file based CMS -API based authoring - command line/endpoint as the interface We will discuss how things can go wrong if you don’t cater to your different authors

1. THIS IS YOUR
PRESENTATION
(or slidedoc) title
The authoring trap:
An overview of
DevPortal
technologies and
their
(dis)advantages
┃1

2. Hello!
Nice to meet you
Contact
▪ Christoph Weber
▪ www.pronovix.com
▪ christoph.weber@pronovix.com
▪ linkedin.com/in/christophweber/
Christoph Weber - Solutions Architect at
Pronovix
┃2

3. It is hard to choose the
correct Developer Portal
tech stack ┃3

4. 5 basic
DevPortal
types
Prebuilt
- Cloud-hosted
DevPortal as a
Service
- DevPortal built into
your API gateway
Custom built
- CMS
- Drupal
- File-based CMS
- JAM Stack
- Decoupled
frontend with
CMS backend
- Static site builder
┃4

5. What you
are really
choosing is
authoring
experience
The platform you
choose will
influence which
authoring
experiences are
available to you
and your team.
Photo by Markus Winkler on Unsplash

6. CMS-based
authoring
Tight coupling
between the content
model and a UI.
Publish directly in the
same system.
Docs as Code
Code repository or
file-based CMS.
CI/CD process to
publish.
API-based
authoring
Command line or
endpoint as the
interface.
┃6
Three
authoring
experiences

7. Carl - marketer
Office 365, Adobe CS
┃7
Janet - developer
IDE, git
Cindy - paralegal
Office 365, others
Three author
personas

8. Carl - marketer
CMS-based, prefers WYSIWYG
┃8
Janet - developer
Docs as Code, version controlled
Cindy - paralegal
CMS-based or API-based
Three author
personas
Their
preferred
authoring
experience

9. The task at
hand
Get API
documentation out,
efficiently,
consistently, and
sustained.
┃9

10. Meet your authors where they are.

11. SaaS Gateway Drupal
JAM
+
CMS
JAM
static
CMS-based
Docs as
Code
API-based
┃11
Authoring
experiences
compared

12. ┃12
Meet your
authors
where they
are.
Preferred
authoring
experience
Engagement
Quality
Consistency
Sustained
success

13. This leaves out Carl with his Marketing background It also gives
him, and
Example 1:
No easy
CMS-based
authoring
Forced tool change
Carl now has to learn
Markdown or some other,
similar system, instead on
focusing on what he already
knows.
Stunted evangelism
Docs-as-code or API-based
authoring gives control over
the layout of his explanatory
evangelism pages
┃13

14. ┃14
Thank you
If you have any questions after the
API the Docs virtual conference
please don’t hesitate to contact us
at:
▪ www.pronovix.com
▪ info@pronovix.com