AI-augmented documentation

I use generative AI every day. It makes me faster. It doesn't make me right. Here's how I use it without letting it write fiction into production docs.

My toolkit

Tool	What I use it for
Claude Code	Working across a whole docs repository: drafting from specs, bulk consistency fixes, checking changes against the style guide, preparing PRs.
Codex	Drafting and refactoring docs alongside code, and generating starting points for examples that I then test.
Cursor	Everyday writing and editing in the editor, plus custom rules that shape how developers document endpoints.

Where AI helps most

First drafts from structured sources

An OpenAPI spec, a Jira ticket and an engineer’s notes are great raw material. AI turns them into a first draft that has the right shape: summary, parameters, request, response and errors. I spend my time on what the draft gets wrong, not on typing headings.

Consistency at scale

Checking 25 endpoints for the same terminology, heading structure and parameter-table format is tedious for a human and quick for a model with the style guide in context. I use it as a tireless first-pass reviewer, then decide which suggestions to accept.

Rules that teach developers

At PayPal World I built custom Cursor rules so that when a developer documents a new endpoint, the editor guides them toward our format: required sections, voice and naming conventions. It’s the style guide showing up at the moment someone is writing, not in a Confluence page they’ll never open. See a sample rule file →

Shorter time from written to published

Formatting fixes, link checks, changelog entries and PR descriptions are all good jobs for automation. Removing that friction is a big part of how one writer keeps up with a whole product team.

Where humans stay in charge

In payments documentation, a confident but wrong sentence is worse than no sentence. AI output is a draft until a human has verified it.

Every API example is tested. If AI wrote a request body, I run it in Postman before it ships.
Engineers and QA still review. AI-assisted docs go through the same PR review as everything else.
Legal, Compliance and Risk content is human-authored. Rules, dispute language and partner communications get careful human drafting and sign-off.
Nothing confidential goes where it shouldn’t. I use approved tools, inside the boundaries my employer sets.

A three-model team in Claude Code

I’m careful about AI spend. Every token is company money, and the most expensive model isn’t the right tool for every step. So I split the work across Claude Code subagents, matching each step to the model it actually needs:

Role	Model	What it does
Orchestrator	Opus	Breaks the task into steps, hands them out, and decides when the work is done. Judgement lives here.
Writer	Sonnet	Does the actual work: drafting endpoint docs, restructuring guides, applying consistency fixes.
Verifier	Haiku	Checks the output against the style guide, the template and the task’s checklist. Quick and cheap.

The three run in a loop. Opus plans, Sonnet writes, and Haiku checks. Anything that fails goes back to Sonnet with specific feedback, and the loop repeats until every check passes. Only then does the work come to me for human review.

  Opus: plan and assign
     │
     ▼
  Sonnet: write ──▶ Haiku: verify ──▶ pass? ──yes──▶ Me: review and ship
     ▲                                  │ no
     └───────── specific fixes ◀────────┘

Why it works:

Tasks finish end to end. I define the task and the checks once, and the loop handles the back-and-forth that would otherwise be me re-prompting.
Quality where it counts, savings where it doesn’t. The strongest model makes the judgement calls, and the cheapest model does the mechanical checking.
The checks are explicit. Writing them forces me to define “done” before any work starts, which is good practice with or without AI.

A typical loop

1. Gather:   spec + ticket + engineer notes
2. Draft:    AI drafts to the template, with the style guide in context
3. Verify:   I test examples in Postman and fix what's wrong
4. Edit:     I rewrite for the reader: order, emphasis, what to cut
5. Review:   PR to engineering and QA
6. Publish:  merge, deploy, done

Why this matters for hiring

Documentation teams are working out right now how to use AI without losing trust. I’ve already done that on a regulated, high-stakes product, as a team of one. I can help a team adopt these tools with guardrails, not just use them myself.

Was this page helpful?