For technical writers, in the age of agents

Write API docs that humans, developers, and agents all want to read.

A free, opinionated course rewritten for 2026 — from REST fundamentals to MCP, function-calling, and writing docs that LLMs can actually use. Taught through one running example: the Greenfield Library API.

Start the course View curriculum

★★★★★

4.8 · 152 reviews · 46 lessons · Free, forever · No sign-in

greenfield.yaml — ai-rewriter

/books/{id}:
  get:
    summary: Get a book by id
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    responses:
      '200':
        description: OK▌

GET /books/{id}
Fetch a single book from the Greenfield Library.

Use this when a reader scans a barcode or an agent resolves a citation. Returns title, author, due date, and the hold queue length so your UI can show "3 ahead of you" without a second round-trip.▌

↻ OpenAPI → Prose (live preview) Claude · Haiku

"The next decade of API documentation isn't about writing more — it's about writing so that an agent at 2am can use your API without paging a human."

— Maya, Lesson 14

What's inside

Eight modules. Forty-six lessons. One opinionated point of view.

Every lesson rewritten with AI as a thread — not a chapter you skip to. You'll learn REST the old-fashioned way (because the fundamentals didn't change), then carry the same fictional Greenfield Library API through structured outputs, function-calling, and MCP servers.

Fundamentals that still matter

REST, HTTP, auth, JSON, and the request-response dance — taught the way a senior writer would actually teach a junior, not the way Wikipedia would.

Modern shapes

Streaming, SSE, WebSockets, gRPC, GraphQL, AsyncAPI — the API shapes that didn't exist when most courses were written.

AI-native docs

Writing for LLMs, MCP, function-calling schemas, agent-friendly errors, and the AI co-pilot tip in every single lesson.

Meet your guide

Hi friend — I'm Maya.

I've documented APIs at three companies you've probably used today. This course is the one I wish I'd had when I started — opinionated, honest about the boring parts, and built around one fictional API (the Greenfield Library) instead of a different vague example in every lesson.

The big change in 2026: I'm not your only co-author anymore. An LLM is reading these docs alongside you, and almost certainly reading yours too. So every lesson ends with an AI co-pilot tip — the actual thing I'd do, with the actual model, today.

I write one lesson a week. I answer questions in the floating chat. I send one email when a new lesson lands. That's the whole deal.

The arc

Eight modules, in the order a working writer would actually need them.

01

Foundations

The internet, the short version · What an API actually is · What an API writer does in 2026 · Information gathering and interviewing the codebase · Audiences: humans, devs, and agents

5 lessons
02

REST, HTTP, and the dance

REST principles · Types of APIs · Anatomy of a URL (part 1) · Anatomy of a URL (part 2) · Request & response · Pagination, idempotency, rate limits · cURL — and why you should still know it · Auth: keys, OAuth, mTLS, and what agents need

8 lessons
03

Data shapes

JSON like you mean it · XML, and when you'll still meet it · Data formats overview · Visualizing data types · Schemas LLMs love: structured outputs

5 lessons
04

Writing the docs

Quickstart that ships in 5 minutes · The bones of an endpoint reference · Bridging the dev/writer gap · OpenAPI without tears · Code samples that don't rot · Errors that actually help

6 lessons
05

Webhooks & async

What webhooks are · Documenting webhooks — beginner · Documenting webhooks — intermediate · Documenting webhooks — expert · AsyncAPI & event-driven docs

5 lessons
06 NEW

Modern API shapes

Streaming APIs & Server-Sent Events · WebSockets for realtime · GraphQL docs in practice · gRPC and Protobuf — when, why, how to document

4 lessons
07 NEW

AI-native documentation

Writing docs for LLMs: agent-friendly patterns · Model Context Protocol: what it is, why you care · Function-calling & tool-use schemas · Prompt-engineering for doc generation · Eval-driven docs: testing docs the way you test code · Building an AI doc assistant for your docs site

6 lessons
08

Practice & ship

Document a REST API — beginner pass · Document a REST API — intermediate pass · Document a REST API — expert pass · Testing your API in Postman — beginner · Testing your API in Postman — intermediate · Testing your API in Postman — expert · Course completion + portfolio guide

7 lessons

Read a sample

Lesson 2 — What an API actually is

~14 min read · Maya · Module 1 — Foundations

Tuesday evening at the branch. I was at the desk updating index cards for the new arrivals. Sam, an old friend of Devon's, came in returning a book and stayed to chat. He watched me for a minute. "You know you could just expose this as an API, right?"

A few days later I was sitting with Devon, looking at what that actually meant. Before we could write a single line of documentation, I had to understand what we were even trying to build.

Continue reading →

Friend — nNew lessons, in your inbox.

No course-bro upsells. About one email every two weeks when a new lesson goes live or a tool changes.