A developer portal is a type of specialist documentation platform that focuses on the semantic technical properties of one or more engineered products. These kind of platforms usually achieve superior out-of-the-box adherence to the DocOps principles of generative content and truth proximity in the specific case of documenting technical properties for known technical products and services.
Some developer portal products include:
| Name | Document Encoding Format | DocOps Automation |
|---|---|---|
| Atlassian Compass | XHTML (with proprietary elements) | Same as Atlassian Confluence |
| Backstage | Markdown (from Git repos such as README.md) | JavaScript/TypeScript plug-ins |
| Cortex | Markdown (from Git repos such as README.md) | REST APIs (SaaS Product) |
| Port | Markdown (from Git repos such as README.md) | REST APIs |
| OpsLevel | Markdown (from Git repos such as README.md) | GraphQL API |
DocOps Automation
The developer portal vendor’s unique selling proposition (USP) is that DocOps use cases in connection to developer information assets (APIs, Git repos, etc) are first class citizens in the platform. In other words, there’s no need to write DocOps automation workflows for those use cases.
The challenge for the DocOps engineering is then connecting non-technical information sources to the developer portal (e.g., GDPR dictionary of personally identifiable information), shall a developer portal be adpoted as the enterprise’s de juris documentation platform.
Limitations
Developer portals’ Achilles’ heel is usually low adherence to the principle of shared responsibility given that they essentially split users into technical and non-technical communities leading to the formation of silos as a result to a proliferation of multiple namespaces. Another problem is that they tend to control the rendering of the technical documentation, prompting users to context switch between business and technical portals.
Ideally, developer portals should do better in terms of decoupled rendering and embedding and blending, allowing the generation of technical documentation using an intermediate document format so that it can be repurposed in multiple contexts.
© 2022-2024 Ernesto Garbarino | Contact me at ernesto@garba.org