Writing Documentation
Prompt the model to write docs grounded in the real code: accurate docstrings, READMEs, and commit messages for a stated audience.
TL;DR
- Ground doc prompts in the real code so descriptions match behavior, not an invented version.
- State the audience and format: docstring, README section, commit message, or changelog entry.
- Review docs for accuracy; confidently wrong documentation is worse than none.
Ground It In Code
Paste The Real ThingDocument the actual function or diff, not a description of it.
"Document this function exactly as
written: <paste>"No Invented BehaviorForbid the model from adding behavior the code does not have.
"Describe only what the code does.
Do not infer extra features."Flag UnknownsHave it mark anything it cannot determine from the code.
"If a side effect is unclear, note
it as TODO, do not guess."Docstrings
Name The StyleSpecify the docstring convention so it fits your toolchain.
"Use JSDoc with @param, @returns,
@throws."Cover The ContractPurpose, parameters, return, errors, and one short example.
what / params / returns /
throws / exampleSkip The ObviousDo not restate types or trivially-named parameters.
Explain the why and the gotchas,
not "id: the id".READMEs & Guides
State The AudienceWho reads it sets the depth, tone, and assumed knowledge.
"For a new contributor on day one."Runnable StepsAsk for exact commands and prerequisites, not vague prose.
"Give copy-paste setup commands,
Node 20, pnpm."Structure ItRequest clear sections: setup, usage, config, troubleshooting.
"Sections: Install, Run, Configure,
Troubleshoot."Commits & Changelogs
From The DiffGenerate the message from the actual staged changes.
"Write a commit message for this
diff: <paste>"Explain The WhyThe body should capture motivation the diff cannot show.
"Subject + body. Body explains why,
not just what."Match ConventionFollow your format so history stays consistent.
"Conventional Commits: type(scope):
summary."Tips
- Paste the actual function or diff and say 'document exactly what this does, do not infer extra behavior'.
- Give your docstring or commit convention as a template so output matches your project.
Warnings
- Models may document intended behavior rather than actual behavior; verify against the code.
- Auto-generated comments that restate the code add noise; ask for the why, not a line-by-line echo.
In Practice
A prompt that documents a real function in your convention, covers the full contract, explains the non-obvious parts, and refuses to invent behavior the code does not have.
- The real function is pasted so the docstring matches actual behavior.
- The convention and required fields are named explicitly.
- The prompt bans invented behavior and restating the obvious.
- A note about the flaky upstream is the kind of 'why' worth documenting.
Write a JSDoc docstring for this function. Document
only what it actually does; do not invent behavior.
Use @param, @returns, @throws, and one short @example.
Explain the non-obvious parts (the retry and the
caching), but do not restate obvious parameter types.
async function getRates(base, { retries = 3 } = {}) {
// retries because the FX upstream is flaky
for (let i = 0; i <= retries; i++) {
try { return await fetchRates(base); }
catch (e) { if (i === retries) throw e; }
}
}
Return only the function with its docstring above it.FAQ
Give the model the real code and tell it to document only what is there, not to infer extra behavior. Then read the result against the code. Docs drift from reality easily, and a confident but wrong docstring misleads every future reader.
Supply the function, name the convention (JSDoc, Google-style, reST), and ask for purpose, parameters, return value, thrown errors, and a short example, while avoiding restating the obvious. Specify the audience so the depth is right.
Yes, from the diff. Give it the staged diff and your format (for example Conventional Commits) and ask for a subject plus a body that explains the why, not just the what. Review it, since the model cannot know the motivation you did not state.
Ask for comments that explain intent and non-obvious decisions, not ones that echo the code. 'Increment i' above i++ is noise; 'retry because the upstream API is flaky' is signal. Tell the model to comment the why.