TL;DR: Technical writing prompts fail most often because "write the documentation" doesn't say which of three different jobs you mean: reference (exhaustive, structured), tutorial (one goal, one path), or conceptual (why, not how). These 30 prompts are split across all three plus API-specific and maintenance work, each with the constraint that actually makes it useful.
Last updated 27 October 2026.
| Jump to | Prompts |
|---|---|
| Reference documentation | 1–8 |
| Tutorials | 9–15 |
| Conceptual and overview docs | 16–20 |
| API documentation prompts | 21–26 |
| Maintenance and team docs | 27–30 |
How do you prompt AI for technical writing?
Quick answer: Name the doc job (reference, tutorial or conceptual), state the audience, and paste the real artifact the doc must be accurate about: the schema, the error payload, the function body or the commit list. Then tell the model what to leave out. Technical writing prompts that skip the pasted source produce plausible text about an API that does not exist.
The reason "write documentation" prompts produce generic output is that "documentation" isn't one task. A reference page for an API endpoint, a tutorial that gets a new user to their first success, and a conceptual page explaining why a system is designed the way it is have almost nothing in common structurally, even when they're about the same feature. A prompt that doesn't name which one it wants tends to produce a page that opens like a tutorial, drifts into reference-style parameter lists halfway through, and never actually explains the concept a confused reader needed.
| Doc type | Answers | Structure | Reader's state of mind |
|---|---|---|---|
| Reference | What are all the options? | Exhaustive, fixed order, scannable | Already knows what they want, needs the exact detail |
| Tutorial | How do I get from nothing to a working result? | Linear, one goal, one path | New to this, wants a single success |
| Conceptual | Why does it work this way? | Explanatory, tradeoff-focused | Has used it, wants to understand it |
Pasting a large schema or a whole module works best with a long-context model; see our notes on Claude's 1M-token context and Gemini's long context. If you reuse the same prompts across a team, reusable prompt variables keep the bracketed fields consistent. For a tool that writes the prompt for you, try the free code documentation prompt generator.
Reference documentation (prompts 1–8)
Reference docs describe a fixed surface (every parameter, every field, every option) exhaustively and in a predictable order, so a reader can scan for the one thing they need without reading top to bottom.
1. Endpoint reference
Write reference documentation for this API endpoint: [paste method,
path, request schema, response schema]. Cover every parameter,
including whether it's required, its type, and its default. Do not
add example use cases; this is reference, not a tutorial.
2. Response object fields
Document every field in this response object: [paste JSON schema
or example response]. State the type, whether it can be null, and
what an empty/absent value means for each field.
3. Function parameter reference
Write the parameter reference for this function: [paste signature
and docstring if any]. Include type, default value, and any
constraint (min/max, allowed values, mutual exclusivity with another
parameter).
4. Error code list
List every error code this endpoint can return: [paste error
handling code or a list of status codes]. For each, state the HTTP
status, the error body shape, and the specific condition that
triggers it — not a generic description of what that status code
usually means.
5. Configuration reference
Write a configuration reference for these settings: [paste config
file or environment variable list]. Group by category, state the
default for each, and flag any that require a restart to take effect.
6. Rate limits
Document the rate limits for this API: [paste actual limits, e.g.
100 req/min free tier, 1,000 req/min paid]. State what happens when
the limit is exceeded (status code, headers, retry guidance) using
the real header names this API actually returns.
7. CLI reference
Write a CLI reference for this command: [paste --help output or
argument parser code]. List every flag, its short and long form, and
whether it takes a value.
8. Authentication methods
Document the authentication methods this API supports: [paste the
actual auth flow, e.g. Bearer token, OAuth2 scopes]. State exactly
which header or parameter carries the credential, not "include your
API key" without saying where.
Notice what these eight prompts have in common besides the topic: every one names a real artifact to paste in (a schema, a signature, a config file, an error list) rather than asking the model to describe the feature from a general sense of what an API "usually" looks like. A parameter reference generated from a plain-English description will confidently list plausible parameter names, defaults and types that may not match what the code accepts. If you don't have a machine-readable schema handy, paste the actual code (the request handler, the function signature, the config-loading logic) instead.
Worked example: schema in, reference out
Here is prompt 1 run twice on a small, invented endpoint. This is illustrative, not a measured result; the endpoint does not exist.
Pasted schema:
POST /v1/widgets
Body: name (string, required, max 80 chars), color (string, optional, one of "red" | "blue", default "red"), tags (array of strings, optional, max 5)
Responses: 201 with the created widget, 400 invalid_request (body shape below), 409 duplicate_name
400 body: { "error": "invalid_request", "field": "<field name>" }
Without the schema (prompt: "Write reference docs for an endpoint that creates a widget"), a typical draft invents a plausible surface: a description field, a quantity integer, a 422 response and a Content-Type note, none of which exist in the real API.
With the schema pasted, the draft stays inside what you gave it:
POST /v1/widgets
Parameters
- name (string, required): up to 80 characters.
- color (string, optional): "red" or "blue". Default: "red".
- tags (array of strings, optional): up to 5 items.
Responses
- 201: the created widget.
- 400 invalid_request: body is { "error": "invalid_request", "field": "<field name>" }.
- 409 duplicate_name: a widget with this name already exists.
The second version is shorter, checkable line by line against the schema, and has nothing in it you would have to delete. That checkability is the point of pasting the real artifact.
Tutorials (prompts 9–15)
A tutorial has one reader, one goal, and one path from a cold start to a working result. It should not try to cover every option along the way, and this is the doc type most likely to go wrong when a prompt tries to make it comprehensive instead of linear.
9. Quickstart to first success
Write a quickstart tutorial that takes a new user from "no account"
to [specific first success, e.g. "first successful API call"] in
under 10 minutes. Assume no prior familiarity with this product.
10. Follow-on tutorial with a prerequisite
Write a tutorial for [specific task] assuming the reader has
already completed [prerequisite tutorial/step]. Do not repeat setup
steps already covered there — link to it instead.
11. Runbook to customer tutorial
Turn this internal runbook into a tutorial a customer could
follow: [paste runbook]. Remove any internal-only steps (accessing
internal tools, checking internal dashboards) and replace them with
what an external user would actually see and do.
12. Framework integration tutorial
Write a tutorial showing how to [integrate this API with a
specific, named framework, e.g. "call this endpoint from a Next.js
server action"]. Use real, runnable code for that framework, not
pseudocode.
13. Troubleshooting tutorial
Write a troubleshooting tutorial for the single most common setup
failure: [describe the failure, e.g. "webhook signature verification
fails"]. Walk through diagnosis first, then the fix, in that order.
14. Steps with expected output
Convert this list of steps into a tutorial with expected output
shown after each step: [paste steps]. State what the reader should
see on screen or in a response after each one, so they can confirm
they're still on track before moving to the next step.
15. Migration tutorial
Write a "migrate from [old approach] to [new approach]" tutorial.
State what breaks if the reader does nothing, and the one-line reason
the new approach is recommended, before the step-by-step migration.
The most common way a tutorial prompt goes wrong isn't factual inaccuracy, it's scope creep: asked for "a tutorial on X," a model will often reach for every related option along the way. Naming the single goal explicitly, and telling it what to leave out ("don't cover authentication methods other than API keys, that's a separate page"), keeps the linear shape a tutorial needs.
Conceptual and overview docs (prompts 16–20)
Conceptual pages answer "why," not "how." They're the pages a reader reaches after the tutorial worked, when they want to understand the system well enough to make their own decisions. The README prompt sits here because it gives a newcomer the overview before any detail.
16. Why the system is designed this way
Explain why this system is designed the way it is: [paste the
actual design, e.g. "webhooks are retried with exponential backoff
for 24 hours"]. State the tradeoff this design makes and what it
would look like if it were designed differently.
17. Core concept in this API's terms
Write a conceptual overview of [a core concept, e.g. "idempotency
keys"] as it applies specifically to this API, not idempotency in
general. Ground every sentence in this API's actual behavior.
18. Two similar features compared
Explain the difference between [two similarly named features,
e.g. "webhooks vs polling"] in this product, specifically when a
developer should choose one over the other for a real use case.
19. README for a repository
Write a README for this repository: [paste the file tree and the main entry point or package manifest]. Sections: what it does in two sentences, prerequisites, install, the smallest working example, where the full docs live. Use only commands that appear in the files I pasted; if something needed is missing, list it as a question instead of guessing.
20. What an error means at a systems level
Explain what this error actually means at a systems level, not
just how to fix it: [paste error]. Cover why the system produces this
error in the first place, for a reader who wants to avoid triggering
it again rather than just fixing it once.
Conceptual pages are the ones most tempting to skip, because a team under deadline pressure can ship the reference and the tutorial and call the docs "done." They also reduce support burden over time: a developer who understands why a rate limit or a retry policy exists is far less likely to file a ticket asking whether it's a bug. For design-level documents, see prompting for technical specs and design docs.
API documentation prompts (prompts 21–26)
API docs carry a specific risk the other categories don't: a wrong parameter name or a wrong error code isn't just unclear, it's actively misleading, because a developer will copy it into working code and get a failure that doesn't match what the docs promised. Every one of these prompts asks for a real schema or real payload as input for exactly that reason.
21. Getting started section
Write a "how this works under the hood" page for [a feature]
aimed at advanced users who've already used the basic version and
want to understand its actual behavior, including any documented
limit or edge case.
22. OpenAPI spec versus code review
Review this OpenAPI spec against the code that implements it: [paste spec excerpt and the handler code]. List every place where they disagree (parameter names, required flags, response codes, types), plus any endpoint or field with no description. Do not rewrite the spec; give me the discrepancy list first.
23. Pagination
Document pagination for this endpoint: [paste actual pagination
params, e.g. cursor, limit]. State the default page size, the max
allowed, and what an empty final page looks like in the response.
24. Webhooks reference
Write a webhooks reference for this event type: [paste payload
schema]. Document the exact field names and types in the payload, the
retry behavior on failure, and how to verify the signature.
25. Versioning and deprecation policy
Write the versioning and deprecation policy section for this API:
[paste actual policy, e.g. "breaking changes ship in a new version
path, old versions supported for 12 months"]. State it plainly, with
no marketing language.
26. SDK usage example
Generate an SDK usage example for [specific language] calling
this endpoint: [paste endpoint details]. Use real, idiomatic syntax
for that language, including error handling for the documented error
codes, not a bare happy-path call.
Maintenance and team docs (prompts 27–30)
27. Pull requests to changelog
Turn this list of merged pull requests into a user-facing
changelog entry: [paste PR titles/commit messages]. Rewrite each into
what changed for the user, drop anything purely internal (refactors,
test changes, dependency bumps with no user-visible effect), and
group by feature/fix/breaking change.
28. Stale doc check against code
Review this doc page for staleness against this current code:
[paste doc + relevant code]. Flag every sentence in the doc that no
longer matches the code, and say specifically what changed.
29. Incident runbook
Write a runbook for this recurring incident: [describe the symptom, e.g. "queue backlog above 10,000 jobs"]. Use these facts: [paste dashboards, commands, owners]. Format: symptoms, quick checks in order, fix steps with the exact commands, how to confirm it is resolved, when to escalate and to whom. Do not invent commands that are not in the facts I gave you.
30. Docstring from actual behavior
Draft a comment/docstring for this function that documents its
actual behavior, including edge cases visible in the code (what
happens on empty input, what it throws): [paste function]. Do not
describe what the function name suggests it does if the code does
something different — document the code, not the name.
For release notes aimed at non-engineers, see stakeholder updates and release notes prompts; to feed prompt 27 cleaner input, use commit message and PR description prompts. Prompt 30 is a short version of what prompting for comments and docstrings covers in full, and 20 AI prompts for documenting workflows and processes covers the non-code side of runbooks.
Before you ship an AI-drafted doc
- Did you paste the actual schema, error codes, or code, or did the model infer them from a description?
- Does the doc match the job you asked for (reference vs tutorial vs conceptual), or does it drift between them?
- Have you personally run the steps in any tutorial, end to end, exactly as written?
- Does anything read as generically true of "APIs in general" rather than specifically true of yours?
- Has a second person, ideally the one who built the feature, confirmed the technical details are accurate?
Adapting these prompts to a stack they weren't written for
Every prompt above is written generically on purpose, so the real work is replacing each bracketed placeholder with something specific to your API, your language, and your team's conventions. A prompt copied with the placeholder left as a description ("paste request schema") rather than an actual schema will produce documentation that reads as generically correct and matches nothing about your real endpoint.
The adaptation people skip most often is pointing the model at an existing example of your team's documentation first. "Here's an existing reference page from our docs: [paste it]. Write a new reference page for this endpoint in the same structure, heading style, and level of detail" produces something that reads as though the same person wrote both pages.
What makes technical writing prompts different from general writing prompts?
Name the job, then paste the real artifact. A generic writing prompt can succeed on reasonable-sounding prose; technical documentation fails the moment a parameter name, status code or default is wrong, because the reader will act on it. The same discipline applies to 25 AI prompts for employee onboarding docs: documentation prompting gets better the more it is grounded in the real system. For the wider coding-prompt picture, see the complete guide to AI coding prompts and MCP.
Keeping docs from drifting out of sync with the code
Documentation debt accumulates quietly until a page that was accurate on the day it shipped is confidently wrong six months later. Run prompt 28 on a schedule, not only when someone notices a discrepancy. A lightweight version: before merging a pull request that changes documented behavior, paste the affected doc section alongside the diff and ask whether anything in the doc is now inaccurate. That catches drift while the context is still fresh.
Stop rewriting prompts. Start shipping.
Turn a rough idea into a structured prompt in one click, inside ChatGPT, Claude, Gemini and 40+ AI tools. 5 free prompts a day, no card. 4.8★ on the Chrome Web Store.
Create a free account