APIs allow systems to interact

API example: Flight booking sites

The essence: Requests and responses

REST API growth phenomenal

Sample scenario: Retrieve weather

Choose an API

Submit a request

curl common for requests

curl -X GET "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=APIKEY&units=imperial"

Sections in API endpoint docs

1. Resource description
2. Endpoints and methods
3. Parameters
4. Request example
5. Response example and schema

Note: API terminology varies drastically from site to site.

Mock example

Real example — Sendgrid

Unique characteristics of API docs

• Reference section has API structure
• Users can try out requests
• Hello-World-like getting started tutorial
• Docs must sell the product — hence custom design
• Split between API ref and conceptual content
• Reference content structured with OpenAPI spec
• Edit on GitHub buttons — pull request workflows
• Not many PDF or localization requirements

OpenAPI specification

Swagger UI Petstore Demo

API conceptual topics

• Getting started (Hello World)
• Authorization
• Status and error codes
• Rate limiting and thresholds
• Code samples and tutorials
• SDKs and sample apps

Getting started

Authorization

Status and error codes

SDKs and sample apps

Auth/pub tools developers prefer

The Docs as Code model

Characteristics of docs as code

• Lightweight markup (e.g., Markdown)
• Static site generators (e.g., Hugo)
• IDE-like text editor (e.g., Atom)
• Version control to manage content (e.g., Git)
• Build from server (e.g., Netlify)

Common API doc tools

• Swagger UI | Swaggerhub
• Stoplight.io
• Readme.com
• ReDoc
• Read the Docs
• Netlify
• GitHub Pages
• Static site generators
• Headless CMS's

A culture of forking and building

Real-time demonstration

Demonstration of docs-as-code publishing...

Why few API writers attend STC

• Tools are different (Expo mostly irrelevant)
• Developer audience different
• Doc'ing code isn't a task-based paradigm
• Structure refers to OAS, not DITA
• Technical ramp-up is steep
• Culture is more unconference style
• Open-source tools are the norm

Getting an API doc job

• Familiarity with 1-2 programming languages or other technical foundations (sample job)
• Experience writing docs for a developer audience (show portfolio)

Tip: Build a portfolio through Season of Docs.

Solving the biggest problems

... the biggest problems with API documentation were also the ones requiring the most technical expertise to solve. Completing, clarifying, and correcting documentation require deep, authoritative knowledge of the API’s implementation. This makes accomplishing these tasks difficult for non-developers or recent contributors to a project. — Martin Robillard and Gias Uddin

Spectrum of involvement

Questions?

The end

Tom Johnson
— idratherbewriting.com
— @tomjohnson
— tomjoht@gmail.com