Architecting Developer eXperience: What Docs Does a Developer Portal Need?

How can you inspire and motivate the developers who use your APIs to become advocates? In this talk, Kathleen takes us on a journey full of practical examples taken from 38 public-facing developer portals.

Developer portals have four main tasks to do:

Self-service support hub: make sure users are able to find out things themselves.

Trust signal: a devportal needs to generate trust.

Documentation database for all its stakeholders. Documentation experience (DocX): what API docs do you need to provide along the user journey?

Big Things Come in Small Packages: API Information in Release Notes

What is a release note exactly? It's a documentation type: new features, bug fixes, change in the way features are to be used, known issues, upgrade paths (to the quickest way to the latest version), deprications.

Deprications are less often talked about. Software moves on, or some functions are not needed any more.

Starting from scratch: we have APIs, now what?

What goes on internally before launching a public-facing developer portal? What problems do you need to tackle? What are the implications of certain ideas and decisions? What comes next?

Goals: a solid suite of APIs, good reference docs, engaged developers

How?

Obvious: from monolithic to microservices — new APIs roadmap — dedicated engineering team — technical writer to document the APIs

Result:

To-do-list: what to keep, what to give up in initial phase?

The platform team becomes a separate business unit that reports directly to the founders and investors.

Not so obvious: learn how to approach developers (via marketing) — buy-in from leadership team — real-life testing (internal hackathon: engineers team up with non-engineers to test the APIs and the API docs) — depricate old APIs

Long-term plans: a platform team that manages all processes related to the developer platform — a developer portal beyond the API references — a DX model — focus on relations within the company to be able to push the product

Results of the first stage: A developer portal with API references and an SDK — get started section — troubleshooting — a basic community page

Moving from GitHub Wiki to a Dedicated Documentation Server

The main ready-made platforms have security issues that a cryptography company cannot afford to have, so they decided to set up their own docs server from scratch.
Lots of documents, have to explain a lot before people are even ready to try the crypto part.
Building the platform - collect references on what it should look like

Main problems and solutions

GitHub migration tools are buggy or clunky -- own developers made custom tools for exporting and cleaning.

Relinking after content migration couldn't be automated.

Increase readability - developers were used to GitHub.

Make the community aware of the new server.

Inside feedback --» fix --» beta version.

Keep entry points & minimal info on GitHub for people to find the new server. RSS feed for their GitHub Wikis.

Going to Infinity and Beyond Documentation with OpenAPI

The OpenAPI Specification, a standard, structured approach for describing APIs, can be used for more than writing/generating reference documentation: you can also apply it for e.g. contract testing, prototyping, client SDKs. Taylor explains.

Self-documenting APIs do not exist, there will always be manual work:

description of endpoints

guides and tutorials (use references with eg. DapperDox, to create examples that auto-update)

DX

Standardization helps, the OpenAPI spec as a collaboration tool:

simpler writing

standard terminology

get certain things done faster

The OpenAPI spec enhances DX:

Design-first: Open API helps create consistency for users

Mocking: dynamically generate examples from the specification

Testing: for accuracy (DREDD), against a style guide (SPECCY)

Feedback: “Making a spec public is a centerpiece to get feedback” — Kin Lane

Going to infinity: explore further what can be done with the help of OpenAPI, such as linting and style guides.

This talk describes the why and how of automatically generating your API specification.

In every tooling case, automation relies upon creating a YAML configuration file: routes, methods, parameters, error messages, and so on for each endpoint.
Each tool provides editors, linters and the like to create and validate these files.

MongoDB chose Swagger: well supported and well adopted.
Starting with an existing API with almost 200 endpoints across dozens of classes, there is not full automation to import.
Swagger has:

You can modify your API code with Swagger’s annotations and your application generates the OpenAPI specification file for you.

Existing tools to generate the API specification file in six different programming languages
With Swagger-Core, the docs team needs only to annotate the existing code (Jersey/JAX-RS for our REST API code).

annotate your API code for Swagger

re-deploy app

compile, download JSON file

Tech writer's development environments set up exactly as of their API developers', to enable working with the codebase in a manner consistent with their development practices.

An unexpected benefit of choosing to work within the API codebase: you learn how the code is organized.

For all further technical details –and there is a lot!– look up Anthony's slide deck, with speaker's notes.