Technical writing is mostly rewriting. The first draft of a doc is never the one users can follow. You write it, then you walk through it as a beginner, then you find the six places you assumed knowledge the reader doesn't have, then you rewrite. The AI doesn't replace that loop — it shortens it.
These are the ten prompts I use in my own writing loop. Each follows Role → Context → Constraints → Output, and each was tested against real docs (real API references, real tutorials, real release notes that shipped to real users). Fill the brackets, run it, then edit. None of these are "write me some documentation." They're instruments for specific failures in the documentation process.
The full set of prompts I use across docs, support, and developer relations lives in the launch pack — but these ten are free to copy.
The structure, once
Every prompt below fills four slots:
- Role — a specific writer, not "a technical writer." Example: "a writer who documents REST APIs for a developer audience that has never used the product before."
- Context — the doc you're working on, the audience, what's already written, what the code does. Concrete inputs.
- Constraints — the rules. Voice, reading level, banned words, required sections, maximum length. This is where prompts go wrong — too few constraints, too much latitude.
- Output — the exact shape of what comes back. "A numbered list of gaps" beats "help me improve this."
Internalize that structure and you can write your own prompts for your own worst documentation problems.
1. Doc audit that finds the actual gaps
The moment: You inherited a docs site. You don't know what's missing, outdated, or wrong. You need an audit, not a vibe check.
Role: You are a senior technical writer auditing an existing
documentation set for gaps and rot.
Context: Product: [name, one-line description]. Docs URL or
pasted table of contents: [paste TOC or link]. Audience:
[beginner developers / experienced integrators / internal
engineers / non-technical admins]. Known recent changes to
the product: [list — features added, APIs deprecated, UI
redesigned].
Constraints:
- Audit for four categories of problem, in this order:
1. Missing docs (things a user needs to do that have no
doc — infer these from the product description and
audience. Example: if there's a "create API key" flow
but no doc on key rotation or permissions, that's a gap.)
2. Outdated docs (things that likely changed but the doc
wasn't updated — flag any doc that references a version,
a UI label, a default, or a limit without a "last verified"
date)
3. Wrong-order docs (prerequisites that come after the step
that needs them; concepts that reference features not yet
introduced)
4. Orphan docs (pages nothing links to; pages that reference
deprecated things)
- For each finding: cite the specific doc/page. No generic
"your authentication docs could be clearer" — that's useless.
"auth.md step 3 references a 'Token' field but the UI now
labels it 'Access Key' as of [version]" is useful.
- Do NOT rewrite anything. This is an audit, not a rewrite.
Output: A markdown table with columns: Category | Doc |
Finding | Severity (blocker/major/minor). Sort by severity
within each category.
The severity column is what makes the output actionable. Without it, you get a list of 40 problems that all feel equal and you fix none of them.
2. Tutorial a true beginner can follow
The moment: You need a getting-started tutorial. The failure mode is writing one that assumes the reader already knows the thing the tutorial is supposed to teach.
Role: You are a technical writer producing a getting-started
tutorial. The reader has never used this product. They may be
new to the broader category.
Context: Product: [name]. What the tutorial should accomplish:
[in one sentence — "set up a webhook receiver and verify it
works"]. Prerequisites the reader can be assumed to have:
[list — e.g., a terminal, Node 18+, a free account].
Prerequisites they CANNOT be assumed to have: [list — e.g.,
prior experience with webhooks, knowledge of our SDK].
Constraints:
- Structure as numbered steps. Each step does exactly ONE thing.
- Every step has three parts: (1) what you're about to do
and why, (2) the command or action, (3) what the output
should look like — quote the literal expected output.
- If a step could fail, add a "If you see [X]" subsection
with the fix. Cover the top 2 failure modes only — not
every possible error.
- No step may reference a concept, file, or tool that hasn't
been introduced in an earlier step. If a step requires a
concept not yet covered, add a prerequisite step.
- Banned phrases: "simply," "just," "obviously," "as you
can see," "it's easy to." If it were simple you wouldn't
be writing a tutorial.
- Reading level: aim for a developer who is competent but
new to THIS. Not a junior, not a staff engineer.
Output: The full tutorial in markdown. Include the intro
(one paragraph on what they'll build and why it matters)
and the success state (how they know it worked).
The "what the output should look like" rule is the most important. Tutorials fail when the reader runs a command, gets output, and can't tell if it's right. Quote the literal success output every time.
3. API reference entry that matches the code
The moment: You're documenting an API endpoint. The failure mode is writing prose that drifts from what the code actually does.
Role: You are a technical writer documenting a REST API
endpoint from its implementation. You do not invent behavior —
you describe what's there.
Context: Endpoint: [METHOD /path]. Source code or behavior
description: [paste the handler, the route definition, or a
precise description of what it does — including auth required,
rate limits, side effects]. Request parameters: [list with
types]. Response shape: [paste the JSON schema or an example
response].
Constraints:
- Document in this exact structure:
1. One-line description (what it does, in plain language,
no marketing)
2. HTTP method + path + required auth (none / API key / OAuth)
3. Parameters table (name | type | required | default |
description — description must state what happens if
omitted, not just "the foo value")
4. Example request (curl, copy-pasteable)
5. Example response (the full JSON, with a comment on any
non-obvious field)
6. Errors (list the status codes this endpoint can return
and what each means — only ones this endpoint actually
returns, not the generic set)
- Every field description must answer: what is it, what shape
is it, what happens if I omit it or send it wrong.
- If the code does something the doc should warn about
(a side effect, a performance cost, a deprecation), include
a "Notes" section. Do not hide warnings in prose.
Output: The reference entry in markdown. No preamble.
The "errors this endpoint actually returns" rule prevents the most common API doc failure: a generic error table that lists every HTTP status code whether or not the endpoint can produce it. Readers learn to ignore those tables. Specific ones get trusted.
4. Release notes that don't bury the breaking change
The moment: You shipped a release. You need notes that users can scan in 30 seconds and that don't hide the one thing that'll break their integration.
Role: You are a technical writer producing release notes
from a list of changes. Your reader is an existing user
deciding whether to upgrade.
Context: Version: [x.y.z]. Change list (from PRs, commits,
or engineering notes): [paste the raw list — messy is fine].
Known breaking changes: [flag any]. Migration required:
[yes/no, and what].
Constraints:
- Structure as three sections, in this order:
1. ⚠️ Breaking changes (if any — lead with these. For each:
what changed, who's affected, the one-line migration
step. If none, write "No breaking changes.")
2. ✨ New (new features and capabilities — each as one
bullet, what it does, no marketing words)
3. 🛠 Fixed (bug fixes — each bullet names the symptom
the user would have seen, not the internal cause)
- Banned: "various improvements," "stability enhancements,"
"performance improvements" unless you can attach a number
or a specific before/after.
- Each bullet is one line. If a change needs explanation,
link to the full changelog or migration guide — don't
expand inline.
- Reading level: a user who skimmed this in 20 seconds
should know (a) whether they need to change their code
and (b) what they get by upgrading.
Output: The release notes in markdown. Ready to post.
The order is the whole prompt. Breaking changes first is the opposite of what most release notes do — and it's the only order that respects the reader's time.
5. Explain-a-concept that doesn't condescend
The moment: You need to explain a concept (webhooks, JWT, event sourcing, idempotency) to an audience that's smart but new to it.
Role: You are a technical writer explaining a concept to a
competent developer who hasn't encountered this specific
concept before. You respect their intelligence.
Context: Concept: [name]. Why they need to understand it:
[the doc or task that requires this concept — e.g., "before
implementing our retry logic, you need to understand
idempotency keys"]. What they already know (safe assumptions):
[list — e.g., "knows HTTP, knows JSON, has used REST APIs"].
What they don't know: [the specific gap this fills].
Constraints:
- Structure:
1. The one-sentence definition (no analogy yet — the
precise technical definition, then a plain-language
restatement)
2. Why it exists (the problem this concept solves —
name the problem before the solution)
3. How it works (a step-by-step walkthrough, with a
concrete example using real values, not abstract
placeholders)
4. The gotcha (the one thing people get wrong about
this concept — the common misunderstanding)
5. When you'd use it vs. not (the decision frame —
when this concept applies and when a simpler
alternative is better)
- Banned analogies that oversimplify: "think of it like
a restaurant" / "imagine a library" / any analogy that
requires explaining the analogy. If an analogy helps,
use it briefly; don't build the whole explanation on it.
- Do not say "simply put" or "in other words" more than once.
- Respect the reader: no "don't worry, it's not as scary
as it sounds." It's not scary. It's a concept.
Output: The explanation in markdown. 400-600 words.
The "gotcha" section is where this prompt earns its keep. AI explanations are good at the what and the how; they're bad at the common misunderstanding because the misunderstanding isn't in the training data — it's in the gap between the concept and how people actually misuse it. Forcing the model to produce a gotcha makes it surface the thing you'd otherwise only learn from a support ticket.
6. Rewrite for reading level without dumbing down
The moment: You have a doc that's technically accurate but written for someone three levels more senior than the actual audience. You need it rewritten without losing precision.
Role: You are a technical writer editing a doc to match the
audience's reading level. You do not remove technical detail.
You make the detail accessible.
Context: Audience: [who they are — e.g., "frontend developers
integrating our API, no backend experience"]. Current doc:
[paste]. What's wrong with it for this audience: [your
diagnosis — e.g., "assumes knowledge of database internals,"
"uses internal jargon," "sentences average 35 words"].
Constraints:
- Keep every piece of technical information. Do not delete
facts, parameters, or warnings to "simplify."
- Change these things:
1. Sentence length — break sentences over 25 words into two.
2. Jargon — replace internal terms with the term the audience
would search for. If you must keep an internal term,
define it inline on first use.
3. Assumed knowledge — if the doc references a concept the
audience doesn't have, add a one-line orientation, not a
paragraph. Link out for depth.
4. Voice — prefer second person ("you configure") over
passive ("is configured"). Active voice for actions.
- Do NOT add analogies, metaphors, or "think of it like."
This is an edit, not a rewrite for tone.
- Do NOT add motivational language ("great job getting this
far!").
- Preserve all code blocks, parameter tables, and structured
data exactly.
Output: The rewritten doc in markdown, same structure.
The "don't delete facts to simplify" rule is the guardrail. The failure mode of reading-level edits is stripping out the precision that made the doc useful. This prompt keeps the precision and fixes the surface.
7. Doc-tree generator from a feature list
The moment: You're starting docs from scratch. You have the product/features. You need the doc structure before you write any page.
Role: You are a technical writer planning a documentation
information architecture from scratch.
Context: Product: [name, one-line description]. Features to
document: [list every feature/capability]. Audience segments:
[list — e.g., "evaluators, integrators, admins"].
Entry points users will arrive from: [e.g., "search for 'how
to X', in-product help link, sales handoff, onboarding email"].
Constraints:
- Produce a doc tree (nested list) with these top-level sections:
- Getting Started (the fastest path to first success)
- Concepts (what you need to understand before the reference
makes sense)
- Guides (task-oriented, one doc per task)
- Reference (API, SDK, CLI, configuration — exhaustive,
not narrative)
- Troubleshooting (symptom-first, not cause-first)
- Under each section, list specific doc titles. Each title
is the task or question the doc answers, not a content type
("Create an API key" not "API Keys Overview").
- For each doc, mark the audience segment(s) it serves.
- Flag any feature that doesn't fit cleanly into a section —
that's a signal the IA is wrong or the feature is poorly
scoped.
- Do not create "Overview" pages for overview's sake. Every
page must answer a question someone would search for.
Output: The doc tree as a nested markdown list. One line per
doc. Audience tags in parentheses.
The "no Overview pages for overview's sake" rule kills the most common IA failure: a docs site full of pages titled "X Overview" that say the same thing as the section above them.
8. Changelog entry from a messy PR description
The moment: Engineering shipped. The PR description is "fixes stuff" and three commit hashes. You need a user-facing changelog entry.
Role: You are a technical writer turning engineering output
into a user-facing changelog entry.
Context: PR title: [title]. PR description: [paste — messy
is fine]. Commits: [paste, or summary]. Files changed: [list
or summary of what subsystem]. The user-visible symptom before
(if a fix): [what users experienced].
Constraints:
- Produce ONE changelog line. Format:
[Type] [Component] — [What changed, in user terms].
- Type: Fixed / Added / Changed / Removed / Deprecated / Security
- Component: the user-facing area (Auth, Billing API, Dashboard),
not the internal module
- What changed: described as what the user will now experience
or no longer experience. Never reference internal files,
functions, or architecture.
- If the change is internal-only (refactor, dependency bump with
no behavior change), output: "Internal: no user-facing change."
Do not invent a user benefit.
- If the change is a breaking change, prefix with "⚠️ Breaking:"
and add the one-line migration step on a second line.
- Maximum 2 lines per entry.
Output: The single changelog entry. Nothing else.
The "internal-only → say so" rule matters. Too many changelogs invent user-facing benefits for refactors. Once users catch you doing that, they stop reading the changelog.
9. Troubleshooting doc organized by symptom
The moment: You have a list of common errors and fixes. You need a troubleshooting page users can scan when something breaks.
Role: You are a technical writer producing a troubleshooting
doc. Users arrive at this page when something is broken and
they're frustrated. They will not read top to bottom.
Context: Product: [name]. Known errors and their fixes:
[paste your list — error messages, symptoms, root causes,
fixes]. Common environmental causes: [list — wrong Node
version, firewall, expired token, etc.].
Constraints:
- Structure as a table of symptoms, not causes. Users search
by what they see, not by what's wrong internally.
- Columns: Symptom (the exact thing the user sees — error
message, unexpected behavior, blank page) | Likely cause
(one line) | Fix (numbered steps, copy-pasteable commands).
- Sort by frequency — the most common symptom first.
- After the table, add a "General debugging" section with
3 universal first steps (e.g., "check your API key,"
"check the status page," "try in a clean environment").
- If a symptom has multiple possible causes, list each cause
with its distinguishing signal ("if you also see X, it's
cause B").
- Banned: "please contact support" as the only fix. If the
fix is "contact support," say what information to include
in the ticket.
Output: The troubleshooting doc in markdown.
Symptom-first organization is the single highest-impact change you can make to a troubleshooting page. Users Google the error message they see; they don't Google "what causes ERR_INVALID_AUTH."
10. Glossary entry that defines, then disambiguates
The moment: You're building a glossary. The failure mode is definitions that are technically correct but useless because they don't distinguish the term from its neighbors.
Role: You are a technical writer producing a glossary entry
for a term that is commonly confused with related terms.
Context: Term: [the word]. Domain: [your product's domain].
Common confusion: [the related terms people mix this up with
— e.g., for "idempotent," confusion is with "pure function"
and "cached"].
Constraints:
- Structure each entry as:
1. One-sentence definition (precise, no analogy, no "simply")
2. An example (a concrete instance, not an abstract one)
3. "Not to be confused with:" — for each related term,
one sentence on the difference. This is the most
important part. The definition alone won't stick if
the reader can't tell the term from its neighbors.
4. "See also:" — cross-references to other glossary terms.
- Definition must use the audience's vocabulary, not more
jargon. If the term is itself jargon, define it in terms
a competent developer would know.
- Maximum 80 words per entry. Glossary entries are looked up,
not read.
Output: The single glossary entry in markdown.
The "not to be confused with" section is the whole prompt. A glossary that defines "authentication" without distinguishing it from "authorization" has failed its reader. The disambiguation is the value.
How I tested these
Each prompt was run against three real docs I'd written or inherited. A prompt that produced a good audit once was an anecdote; I kept the ones that produced good audits across an API reference, a tutorial, and a troubleshooting page.
Then I checked generalization: does the tutorial prompt work for a CLI tool the same way it works for a web API? Does the release-notes prompt work for a library the same way it works for a hosted product? The ones above generalized.
Finally, I read every output as a hostile reader — looking for hallucinated parameters, invented error codes, sections that sounded right but were wrong. The constraints (quote literal output, only list errors the endpoint actually returns, mark internal changes as internal) exist because those are the failure modes. The prompt structure is designed to make the failure modes hard to produce.
What's in the full pack
These ten are the technical-writing slice. The full launch pack has seven prompts that cover the core docs-to-launch workflow — release notes, API reference, tutorials, README, and the audit method. There's a larger productivity library with 30 prompts across docs, support, engineering, and ops if you want the broader set.
The prompts aren't the asset. The structure is. Once you can write Role→Context→Constraints→Output for the worst part of your documentation process, you stop needing other people's prompt libraries.
The best thing you can do with this is steal the structure, write a prompt for the doc task you hate most, and run it three times on three real inputs. That's the entire method.
Top comments (0)