30 AI Prompts for Technical Writing and API Docs

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.

Why Do "Write Documentation" Prompts Produce Generic Output?

Because "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 underlying concept a confused reader needed.

Naming the job up front, and pairing it with the real technical details (the actual parameter names, the actual error codes, the actual constraint), is most of what separates a usable draft from a generic one. The 30 prompts below are grouped by job for that reason.

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. 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. 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. 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. 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. 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. 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. 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. 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. That's the load-bearing part of a reference prompt. A parameter reference generated from a plain-English description of the endpoint will confidently list plausible parameter names, defaults, and types that may not match what the code actually accepts, because there was never a real schema for the model to check itself against. 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 — reference docs generated from real code are still meaningfully more accurate than reference docs generated from a description of that code.

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. 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. 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. 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. 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. 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. 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. 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, turning a ten-minute walkthrough into a survey of the whole feature area. 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 actually needs.

Conceptual and Explanatory Docs (Prompts 16–21)

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.

16. 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. 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. 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. Write an architecture overview for [a specific subsystem], aimed
at a developer integrating with it, not one aimed at someone building
it. Exclude internal implementation details that don't affect how
someone integrates.

20. 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.

21. 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.

Conceptual pages are the ones most tempting to skip entirely, because a team under deadline pressure can always ship the reference and the tutorial and call the docs "done." They're also the pages that most reduce support burden over time, because 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. When you're deciding what to write next and time is limited, a conceptual page for your single most support-ticket-generating feature is usually a better investment than a sixth reference page nobody's asked about yet.

API-Specific Documentation (Prompts 22–26)

22. Write the "getting started" section for this API's docs: base
URL, how to obtain a credential, and the smallest possible working
request. Use the actual base URL and credential name, not
placeholders like "your-api-key".

23. 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. 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. 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. 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.

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 the five prompts below asks for a real schema or real payload as input for exactly that reason.

Maintenance and Team Docs (Prompts 27–30)

27. 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. 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. Write a style-guide entry for how this team documents [a
recurring pattern, e.g. "deprecation notices"], based on these three
existing examples: [paste examples]. Extract the actual pattern used,
don't invent a new one.

30. 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.

Adapting These Prompts to a Stack They Weren't Written For

Every prompt above is written generically on purpose, which means the actual work of using one is filling in the bracketed placeholder with something specific to your API, your language, and your team's existing conventions. A prompt copied verbatim 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 that matters most, and the one people skip most often, is pointing the model at an existing example of your team's documentation before asking for a new page in the same style. "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. Asking cold, with no example, tends to produce documentation that's individually fine but collectively inconsistent, page style drifting every time someone generates a new one.

What Makes Technical Writing Prompts Different From General Writing Prompts

The pattern across all 30 is the same: name the job (reference, tutorial, conceptual, changelog, docstring), then paste the real artifact the docs need to be accurate about (schema, error payload, commit list, function body). A generic writing prompt can succeed on vibes and reasonable-sounding prose. Technical documentation fails the moment a parameter name, a status code, or a default value is wrong, because the reader will act on it and hit a mismatch between the doc and the actual system.

This is the same discipline behind 25 AI prompts for employee onboarding docs — documentation prompting in general gets better the more specifically it's grounded in the real process or system it's describing, rather than a generic template for "how to write an onboarding doc" or "how to write API docs" in the abstract.

Keeping Docs From Drifting Out of Sync With the Code

Documentation debt accumulates the same way technical debt does: quietly, one small unreflected change at a time, until a page that was accurate on the day it shipped is confidently wrong six months later. Prompt 28 above (reviewing a doc page against current code) is worth running on a schedule, not just when someone happens to notice a discrepancy, precisely because nobody happens to notice most of them until a user does.

A lightweight version of this costs very little: before merging a pull request that changes a documented behavior, paste the affected doc section alongside the diff and ask whether anything in the doc is now inaccurate. This catches drift at the moment it's introduced, when the context for what changed and why is still fresh, rather than months later when reconstructing that context costs far more than writing the correction would have.

Before You Ship an AI-Drafted Doc

1. Did you paste the actual schema, error codes, or code, or did the model infer them from a description?
2. Does the doc match the job you asked for (reference vs tutorial vs conceptual), or does it drift between them?
3. Have you personally run the steps in any tutorial, end to end, exactly as written?
4. Does anything read as generically true of "APIs in general" rather than specifically true of yours?
5. Has a second person, ideally the one who built the feature, confirmed the technical details are accurate?