Skip to main content

Documentation With AI

5 min read
Tech WriterDevrel

Tech Writer

AI drafts. You edit. Your job shifts from 'write from scratch' to 'curate, correct, and add the stuff AI gets wrong.' Embrace it.

Devrel

AI can't build community. It can draft blog posts and release notes. You add the voice and the 'why should I care?'

Api Dev

AI generates API reference from OpenAPI. It doesn't explain when to use this endpoint vs. that one. That's your value add.

Documentation With AI

TL;DR

  • AI is excellent at reference docs, API summaries, and "what does this function do?" extracted from code.
  • AI is bad at tone, accuracy, and "what does the developer actually need to know?"
  • Best use: AI drafts. Human edits. Human owns the "why" and the "gotchas."

Docs teams got squeezed because AI can generate documentation. The squeeze is real. So is the opportunity — if you position right.

Where AI Shines

API Reference and Function Docs

Input: Code + docstrings or OpenAPI spec.

Output: Structured reference. Parameters, return types, examples. Often accurate when the source is accurate.

Caveat: If the code is wrong or the spec is stale, AI documents the wrong thing. Garbage in, garbage out.

Boilerplate Tutorials

Prompt: "Write a tutorial for setting up X with Y."

Output: Step-by-step. Installation, config, first run. Works for popular, well-documented tools.

Caveat: Version drift. "This worked in v2, we're on v4 now." AI training data has a cutoff. You need to verify.

Auto-Generated Changelogs

Input: Git history or release notes.

Output: A draft changelog. "Added X, fixed Y, deprecated Z."

Caveat: AI doesn't know impact. "Fixed memory leak" might be critical. AI will list it same as "fixed typo."

Where AI Struggles

Accuracy and Nuance

  • "This API is idempotent." Is it? AI might guess. Wrong docs are worse than no docs.
  • "Use this for small datasets." What's "small"? 1K? 1M? AI doesn't know your domain.
  • "This is deprecated." When? What replaces it? AI might hallucinate a successor.

Tone and Developer Empathy

  • "You might want to consider..." vs. "Do this or you'll get burned." AI tends toward bland. Good docs have personality and urgency where it matters.
  • "Here's what we wish we'd known." — That's human. War stories, gotchas, "we did X and regretted it." AI doesn't have those.

Context and "Why"

  • "When should I use this endpoint vs. that one?" — Product and architectural context. AI doesn't know.
  • "What are the trade-offs?" — Design decisions. Human territory.
  • "What's broken that we're working on?" — Current state of the system. AI can't maintain that in real time.

How to Use AI for Documentation

  1. Use AI for first draft. "Draft docs for this API." Get the structure. Don't publish without review.
  2. Verify everything. Every claim. Every example. Run the code. Check the versions.
  3. Add the human parts. Gotchas. "Why we built it this way." "Don't do X because Y."
  4. Own the voice. Adjust tone. Add humor, urgency, or calm depending on the audience. AI is generic. You're not.

Quick Check

AI drafts API docs from your OpenAPI spec. What's the critical gap?

You write every doc from scratch. Hours per API, per tutorial. Or docs lag behind code and become stale.

Click "With AI" to see the difference →

Do This Next

  1. Generate docs for one API or function you know well. Review the output. How much would you keep? What's wrong or missing?
  2. Write one "AI couldn't do this" section. Something that requires institutional knowledge or judgment. That's your moat.