How to Write Docs with AI
Good docs explain how to use the code, not how clever it looks. Ask the AI for docstrings, README steps and “why” notes — then check every command against reality.
In short: point the AI at the real function or script, ask for audience + format, verify commands by running them, and never invent product URLs or version numbers.
Why AI helps with docs
Writing first drafts is slow. AI turns a function into a clear docstring or a short README section quickly. It also invents flags that do not exist. Your job is to run the commands and fix the lies.
What to ask for
- Docstring / JSDoc / XML doc: inputs, outputs, errors, one example.
- README section: install → run → test, in vertical steps.
- Changelog / PR summary: what changed and why, in plain English.
- Audience: beginner teammate vs API consumer — say which.
How writing docs flows
Example: docstring for EMI
Add a clear Python docstring to monthly_emi. Include formula in one line, Args, Returns, Raises. Keep the code logic unchanged. Easy English.
def monthly_emi(principal: float, annual_rate_percent: float, months: int) -> float:
"""Return EMI for a reducing-balance loan.
Formula: EMI = P * r * (1+r)^n / ((1+r)^n - 1)
where r is the monthly rate (annual_rate_percent / 12 / 100).
Args:
principal: loan amount in rupees (must be > 0).
annual_rate_percent: yearly interest, e.g. 10 for 10%.
months: tenure in months (must be > 0).
Returns:
EMI rounded to 2 decimal places.
Raises:
ValueError: if principal or months is not positive.
"""
if principal <= 0 or months <= 0:
raise ValueError("principal and months must be > 0")
if annual_rate_percent == 0:
return round(principal / months, 2)
r = annual_rate_percent / 12 / 100
factor = (1 + r) ** months
return round(principal * r * factor / (factor - 1), 2)How to write docs step by step
- Open the real file in the IDE so the AI sees current signatures.
- Say the format: Google-style docstring, JSDoc, or “README steps only”.
- Ban marketing language. Ask for verbs: Install, Run, Test.
- Run every shell command the draft suggests. Delete what fails.
- Keep docs next to the change so they do not rot.
| Doc type | Good ask |
|---|---|
| Function docstring | “Args, Returns, Raises, one example; no essay.” |
| README quickstart | “5 vertical steps: clone, install, env, run, test.” |
| API note | “Request shape + error codes we actually return.” |
| Internal ADR | “Context, decision, consequences — one page.” |
Settings tip
- Project rules: “Docs must match real CLI flags; prefer short steps.”
- For README work, paste package.json / pyproject scripts so versions stay honest.
- Prefer a careful model for long docs; use a fast model for one-line comment cleanup.
Quick quiz
1. What must you verify in AI docs?
Every command, flag and version against the real project.
2. What belongs in a docstring?
Inputs, outputs, errors, and a small example — not a blog post.
3. Where should docs live relative to a change?
In the same PR / commit when possible.
4. What tone works best?
Short, plain English verbs.
Save tokens and money
Generate one section at a time (Quickstart, then Config). Huge “document the whole monorepo” prompts waste tokens and invent details.