Best Claude prompts for technical writers in 2026

Three reasons working tech writers cite when they switch. First: Claude tends to preserve technical terms exactly as written — it will not silently rename `user_id` to `userId` or change `POST /v2/widgets` to `POST /widgets/v2` mid-paragraph, which is the failure mode that ships broken docs. Second: long context windows mean you can paste an entire OpenAPI spec, the existing reference section, and three competing style guides into a single prompt and get a consistent rewrite. Third: structured XML-style prompting (per Anthropic's own prompt engineering guide) maps cleanly onto the structural thinking documentation already requires.

The economics: Claude Pro (per Anthropic's pricing) handles the daily volume of a working tech writer comfortably. For docs teams running prompts at scale via the Anthropic API, per-token pricing varies by model tier. A docs team measured on time-to-publish for new SDK features recovers the cost in the first sprint they use the API-reference scaffolder.

What Claude is not good at: running your code, hitting the live API to verify a response payload, or guaranteeing that a sample request actually executes. Treat every code block it emits as a draft until a developer or your own test runner confirms it works.

**The prompt:**

``` Below is an OpenAPI 3.1 spec for the [PRODUCT] [VERSION] API. Generate a reference page for the [ENDPOINT] endpoint following the Google developer documentation style guide. Structure: (1) one-sentence summary, (2) HTTP method + path, (3) auth requirements, (4) path parameters table (name, type, required, description), (5) query parameters table, (6) request body schema with field-level descriptions, (7) one curl example with realistic values, (8) one response example per documented status code, (9) error reference table. Do not invent fields. If a field is missing a description in the spec, output `[DESCRIPTION NEEDED]` instead of guessing. Use sentence case for headings. OpenAPI spec: [PASTE] ```

**Why it works:** The 'do not invent fields' rule and the explicit `[DESCRIPTION NEEDED]` token stop the most common reference-doc failure — Claude smoothing over gaps by inventing plausible-sounding descriptions that ship as authoritative. The Google style guide anchor produces sentence-case headings and consistent tense. Realistic curl values (instead of `string`, `string`, `string`) cut the developer's mental load reading the example.

**Sample output (condensed):** '### Create a widget — `POST /v2/widgets`. Creates a new widget owned by the authenticated workspace. Requires `widgets:write` scope on the bearer token. **Path parameters:** none. **Request body:** `name` (string, required) — display name shown in the dashboard. `color` (string, optional) — hex code; defaults to `#1f2937`. `metadata` (object, optional) — `[DESCRIPTION NEEDED]`. **Example:** `curl -X POST https://api.example.com/v2/widgets -H "Authorization: Bearer $TOKEN" -d '{"name":"Production gauge","color":"#10b981"}'`. **Responses:** `201 Created` returns the full widget object; `401` invalid token; `409` workspace widget cap reached.'

**The prompt:**

``` Scaffold a tutorial following the Diataxis framework. The tutorial teaches a beginner [GOAL] using [PRODUCT]. A tutorial is learning-oriented — the reader follows along and reaches a concrete end state. Produce: (1) one-sentence promise of what the reader will build, (2) prerequisites (versions, accounts, prior knowledge), (3) 5-8 numbered steps, each with intent line, code block, expected output, and `if you see X, do Y` failure branch, (4) a 'you have built' checkpoint, (5) explicit next-step pointers to the how-to guide and the reference page (not a 'further reading' dump). Do not explain concepts — link to the explanation. Do not branch into options — one path only. Tutorial goal: [GOAL] Reader background: [X] ```

**Why it works:** The Diataxis framework draws a hard line between tutorials (learning), how-tos (problem-solving), reference (information), and explanation (understanding). Most prompt outputs blur tutorials and how-tos, which is why the reader ends up confused. Banning concept explanation and option branching keeps the tutorial on the single happy path Diataxis prescribes. The failure-branch lines per step are what separate a tutorial that actually works from one that loses readers at step 3.

**Sample output (condensed):** 'You will build a working webhook receiver that captures `widget.created` events and writes them to a SQLite file. Prerequisites: Node.js 22+, a free [PRODUCT] workspace, basic terminal familiarity. Step 1 — Install the SDK. `npm install @example/sdk@^4`. Expected: `added 1 package`. If you see `EACCES`, run with your user instead of sudo. Step 2 — Generate a signing secret. [...] You have built: a webhook receiver. Next: see the [signature verification how-to] when you deploy to production; see the [Webhooks reference] for the full event catalog.'

**The prompt:**

``` The doc below mixes conceptual explanation, task instructions, and reference detail on one page — the Diataxis anti-pattern. Split it into three clean pages: (1) the concept page (what it is, why it exists, mental model, tradeoffs — no steps), (2) the how-to page (step-by-step for one specific job — no concept teaching), (3) the reference entry (fields, parameters, return values, errors — no narrative). For each new page output: proposed slug, h1, intro paragraph, h2 outline, and the source paragraphs that should move there. Flag any paragraph that does not belong in any of the three. Do not rewrite the prose yet — only re-shelve it. Source page: [PASTE] ```

**Why it works:** Re-shelving before rewriting forces the structural decisions first and the prose-polishing second, which is the order the Diataxis guidance and most senior tech writers recommend. The 'flag anything that does not belong' line surfaces the marketing copy, internal asides, and stale roadmap notes that almost always live on overloaded pages. Outputting source paragraph pointers (not rewritten prose) keeps you in control of the voice on the rewrite pass.

**Sample output (condensed):** 'Page 1 — Concept: slug `concepts/widgets`, h1 'What are widgets?', moves paragraphs 1, 2, 4, 9 (mental model + the diagram). Page 2 — How-to: slug `how-to/create-a-widget`, h1 'Create your first widget', moves paragraphs 5, 6, 7 (the steps) + the troubleshooting subsection. Page 3 — Reference: slug `reference/widgets`, h1 'Widget object', moves paragraphs 10-14 (the field table). Unshelved: paragraph 3 (roadmap statement — belongs on the changelog), paragraph 8 (marketing claim about competitors — remove).'

**The prompt:**

``` Rewrite the error message below to be developer-friendly per the Google developer documentation style guide. Constraints: (1) lead with what went wrong in plain language, (2) name the likely cause, (3) include one concrete next step (not 'see the docs'), (4) preserve any stable error code or correlation ID, (5) under 200 characters for the inline message, (6) optionally provide a longer 'expanded' version under 600 characters for docs. Active voice. No 'oops' or apologies. No blame language ('you provided', 'invalid input you sent'). Match Microsoft Writing Style Guide tone — direct, neutral, helpful. Original error: [PASTE] Context (what the developer was trying to do): [X] ```

**Why it works:** Both the Google developer style guide and the Microsoft Writing Style Guide call out blame language as the dominant failure mode in error UX. The character caps stop Claude from drafting a paragraph where a sentence is needed. Preserving the error code is the line that keeps the rewrite supportable — devops still needs to grep for `ERR_RATE_LIMIT_TIER_1` six months from now.

**Sample output (condensed):** 'Inline (187 chars): `Request blocked: workspace exceeded the free-tier rate limit of 60 requests/minute (ERR_RATE_LIMIT_TIER_1). Wait 47 seconds or upgrade at example.com/billing.` Expanded (520 chars): `This workspace is on the free tier, which allows 60 requests per minute per API key. The current key sent 84 requests in the last 60 seconds. Two fixes: wait until the rate window resets (47 seconds from now per the Retry-After header), or upgrade to a paid tier with a 6,000 req/min ceiling. Code: ERR_RATE_LIMIT_TIER_1. Correlation: req_a1b2c3.`'

**The prompt:**

``` Below is a raw git log from [DATE RANGE] for the [PROJECT] repo, ~[X] commits. Produce a Keep-a-Changelog-format entry for version [Y]. Group commits under: Added, Changed, Deprecated, Removed, Fixed, Security. Rules: (1) merge fixup/revert/typo commits into the canonical change, (2) drop internal-only commits (CI config, lint fixes, refactors with no user-visible effect) unless they changed API surface, (3) translate commit-speak ('bump deps', 'fix flake') into user-facing language, (4) flag any commit whose user impact is unclear with `[NEEDS REVIEW]`, (5) order each group by impact descending. Do not invent breaking changes. Active voice. No marketing adjectives. Git log: [PASTE] ```

**Why it works:** The Keep a Changelog categories are the convention most docs sites and changelog tools expect. Banning 'invented breaking changes' is load-bearing — Claude will sometimes upgrade a 'fix' commit to a 'breaking change' to sound thorough, which then triggers customer panic the engineering team has to walk back. The `[NEEDS REVIEW]` flag is how you stay honest about the commits where you cannot tell from the message alone what shipped.

**Sample output (condensed):** '## [4.2.0] — 2026-06-09. ### Added: Bulk widget creation endpoint (`POST /v2/widgets/bulk`, up to 1,000 per request). Webhook signing-secret rotation without downtime. ### Changed: `GET /widgets` now returns paginated results by default (page size 100). ### Deprecated: `metadata.tags` field — use `tags` array instead; deprecation removal in v5. ### Fixed: Webhook retries now respect the `Retry-After` response header. Workspace export no longer truncates names over 64 chars. ### `[NEEDS REVIEW]`: commit `a4f9c2` 'fix the thing in the prod handler' — unclear user impact, check with author before publishing.'

**The prompt:**

``` Below is the structured changelog for [PRODUCT] [VERSION]. Draft a 300-400-word release-note narrative for the blog/newsletter version. Structure: (1) one-sentence headline naming the biggest user-facing change, (2) opening paragraph that names who benefits and how their day changes, (3) one paragraph per top-2 features with a concrete before/after, (4) one paragraph on breaking changes with the migration link, (5) one-line pointer to the full changelog. Tone: direct, developer-respectful, no marketing puffery. Ban: 'we're excited to announce', 'powerful', 'seamless', 'best-in-class', 'revolutionizing'. Active voice. No exclamation marks. Changelog: [PASTE] ```

**Why it works:** Release notes are where docs teams get pulled into marketing voice they did not sign up for. The banned-phrase list is the fastest filter — every one of those phrases is in the Microsoft Writing Style Guide's word list to avoid for technical communications. The before/after structure forces concrete utility; the migration-link paragraph is the line that protects the customers most likely to be burned by a breaking change.

**Sample output (condensed):** 'Bulk widget creation lands in v4.2. Teams provisioning more than 50 widgets per environment used to script a sequential loop and hit the per-key rate limit; v4.2 ships a `/widgets/bulk` endpoint that accepts up to 1,000 per request and returns a single response with per-row status. Before: ~3 minutes to create 500 widgets, with retry handling on the caller. After: under 4 seconds, with row-level errors in the response body. Webhook secret rotation also ships this release — rotate without re-handshaking your receiver. Breaking change: `GET /widgets` defaults to paginated responses; if your integration consumed the un-paginated list, see the [pagination migration guide]. Full changelog: [link].'

**The prompt:**

``` Below is the file/directory tree and `package.json` for [REPO]. Draft a README for [AUDIENCE — internal devs / external OSS users / SDK consumers]. Sections, in order: (1) one-sentence project promise, (2) status badge row placeholder, (3) install (one command per supported manager), (4) 10-line quickstart that produces visible output, (5) usage — top 3 use cases with snippets, (6) configuration — env vars table (name, type, default, description), (7) development — run tests + lint + dev server, (8) contributing pointer, (9) license. Do not invent commands. If install/test/lint scripts are not in package.json, mark them `[CONFIRM SCRIPT]`. Match the Google developer documentation style guide for tone. File tree: [PASTE] package.json: [PASTE] ```

**Why it works:** README quality is what separates an OSS project that gets stars from one that gets forks. Most generated READMEs invent install commands and test scripts that do not exist in the actual `package.json` — the `[CONFIRM SCRIPT]` flag is how you stay honest. The 10-line quickstart constraint is borrowed from the Write the Docs README guidance — anything longer is a tutorial in disguise.

**Sample output (condensed):** '# example-sdk — Type-safe Node SDK for the Example platform. ![CI] ![npm] ![license]. ## Install: `npm install @example/sdk` (also `pnpm add`, `yarn add`). ## Quickstart: ```ts\nimport { Example } from "@example/sdk";\nconst client = new Example({ apiKey: process.env.EXAMPLE_KEY });\nconst widget = await client.widgets.create({ name: "hello" });\nconsole.log(widget.id);\n```. ## Configuration: `EXAMPLE_KEY` (string, required) — workspace API key. `EXAMPLE_BASE_URL` (string, default `https://api.example.com`) — override for self-hosted. ## Development: `[CONFIRM SCRIPT]` — package.json does not declare a `test` script. ## License: MIT.'

**The prompt:**

``` Below is a file from [PROJECT]. Audit and improve the comments — code is read-only. For each function/class/exported member: (1) flag missing or stale doc comments, (2) propose a TSDoc/JSDoc/Python docstring block matching the file's language convention, (3) include `@param`, `@returns`, `@throws` where applicable, (4) preserve any existing useful comment; do not delete dev-intent comments ('// HACK', '// TODO'), (5) flag any function whose body contradicts its current comment with `[STALE — body does X, comment says Y]`. Use sentence case. One blank line between block and code. Do not modify executable code. File: [PASTE] ```

**Why it works:** The 'code is read-only' rule prevents the failure mode where Claude rewrites the function while adding comments and ships a subtle bug. The `[STALE]` flag is the highest-leverage output — stale doc comments are worse than missing ones because developers trust them. Preserving 'HACK' and 'TODO' comments respects the lived knowledge of the codebase that future maintainers need.

**Sample output (condensed):** 'Line 12 — `parseSignature()`: existing comment says "verifies HMAC-SHA256 signature" but body uses `timingSafeEqual` against a SHA-1 digest. `[STALE — body does SHA-1, comment says SHA-256]`. Suggested TSDoc: `/** Verifies a request signature against the configured signing secret. @param raw — the request body as a Buffer. @param header — value of the X-Signature header. @returns true if the signature matches; false otherwise. @throws if the signing secret is not configured. */`. Line 47 — `// HACK: works around upstream bug #4421` — preserve as-is.'

**The prompt:**

``` Audit the documentation page below against a senior-tech-writer rubric. Produce a 12-item checklist with pass/fail/partial per item and one-line evidence. Categories: (1) page has a clear job-to-be-done in the first 100 words, (2) Diataxis-aligned (only one of: tutorial/how-to/reference/explanation), (3) sentence-case headings, (4) active voice (flag passive instances with line refs), (5) no jargon undefined on first use, (6) every code block is runnable as written, (7) every link resolves to a stable URL (no `localhost`, no internal staging), (8) accessibility — images have alt text, tables have headers, (9) every claim of behavior maps to a parameter or response in the spec, (10) tested against the latest product version (date in frontmatter), (11) entry/exit pointers — links in and links out to adjacent docs, (12) no marketing prose. Output: table + a 3-line summary of the top fixes. Doc page: [PASTE] ```

**Why it works:** Twelve items is the upper bound of what a writer can mentally check on one read. The rubric blends Diataxis structural checks with the Google style guide accessibility requirements and the Microsoft style guide tone rules. Forcing evidence per line prevents Claude from rubber-stamping a fail-list — every fail comes with a line ref so you can fix it without re-reading the whole page.

**Sample output (condensed):** '| # | Check | Result | Evidence |\n| 1 | Job-to-be-done in first 100w | Partial | Mentioned in para 2 not lede |\n| 2 | Diataxis-aligned | Fail | Mixes tutorial steps with reference table |\n| 3 | Sentence-case headings | Pass | All h2s consistent |\n| 4 | Active voice | Partial | Lines 24, 51, 88 passive |\n| 5 | Jargon defined | Fail | 'idempotency token' used 4× before definition |\n| 6 | Code runnable | Fail | Line 33 imports `widgets.create` — does not exist in v4 SDK |\nTop fixes: split into concept + how-to (Check 2); fix line-33 import (Check 6); define idempotency token on first use (Check 5).'

**The prompt:**

``` Below is a doc written for engineers. Rewrite for [CUSTOMER AUDIENCE — e.g., 'admins setting up the integration without coding experience']. Rules: (1) keep every concrete instruction and number — translate jargon only, (2) move acronyms and protocol names to footnotes/glossary links rather than inlining definitions, (3) replace conceptual references the audience does not need with the user-facing equivalent ('your dashboard' not 'the React frontend'), (4) preserve any warning, security note, or 'do not' — never soften these, (5) match the Microsoft Writing Style Guide reading-grade target (~8th grade). Output a side-by-side diff: engineering line | customer-audience line. Flag any line where translation is impossible without losing accuracy. Engineering doc: [PASTE] Audience profile: [X] ```

**Why it works:** Translation prompts usually fail because they soften warnings — the one place tech writers cannot afford to lose specificity. Preserving warnings verbatim is the rule that protects support tickets six months later. The side-by-side diff format makes engineering review fast — the SME can scan the right column and flag any loss of precision in a 10-minute pass.

**Sample output (condensed):** '| Engineering | Customer-facing |\n| 'Configure the OIDC client with PKCE and a 5-minute access-token TTL' | 'In your identity provider, add a new app and use the values from your dashboard. Sign-in sessions last 5 minutes by default.' |\n| 'Rotate the JWT signing key every 90 days' | 'Rotate your signing key every 90 days from Settings > Security.' |\n| WARNING: 'Do not commit the client secret to source control' | WARNING: 'Do not commit the client secret to source control' (preserved verbatim) |\n| `[FLAG]` 'Use SCIM 2.0 for user provisioning' — no customer-facing equivalent; needs SME on whether to keep SCIM term or replace with 'automatic user sync' |'

**The prompt:**

``` Below is the current table of contents for the [PRODUCT] docs (~[X] pages). Restructure for search-and-scan: (1) group by Diataxis category — Tutorials, How-tos, Reference, Concepts, (2) within each, order by likely first-touch frequency for a new user (most common first), (3) rewrite each entry title as the question or task the reader has in their head (not the feature name), (4) flag any current entry that is two pages collapsed into one (split candidates) or two entries that are the same page (merge candidates), (5) list any obvious gaps where a reasonable user search would land on nothing. Output the new TOC + a separate Gaps list + a Splits/Merges list. Current TOC: [PASTE] Top 20 internal-search queries (last 90 days): [PASTE] ```

**Why it works:** Feature-name titles ('Widget configuration') lose to task-language titles ('Configure your first widget') in both internal search and Google. Pulling in the top 20 internal-search queries grounds the rewrite in what users actually type — per Write the Docs analytics guidance this is the single highest-ROI input for IA work. The Gaps list is the planning document for the next quarter's writing roadmap.

**Sample output (condensed):** '### Tutorials. 1) Build your first widget in 10 minutes. 2) Wire up a webhook receiver. ### How-tos. 1) Rotate a signing secret without downtime. 2) Configure SSO with your identity provider. 3) Export workspace data. ### Reference. 1) Widget object. 2) Webhook events. 3) API errors. ### Concepts. 1) How widgets fit into your account model. 2) Rate limits and quotas. **Gaps:** 6 of top-20 internal searches return zero — 'csv import' (high), 'sandbox environment' (high), 'IP allowlist' (medium). **Splits:** 'Configuration' is 7 pages collapsed — split per surface. **Merges:** 'Quickstart' + 'Getting started' are the same content.'

**The prompt:**

``` Below is a CSV export from [ANALYTICS TOOL] for the [PRODUCT] docs site, last 90 days. Columns: url, pageviews, avg_time_on_page, bounce_rate, exit_rate, internal_search_landed, support_tickets_referencing_url (if present). Produce a doc-debt prioritization with the top 15 pages to fix, sorted by impact × effort. For each: (1) the signal that flagged it (high traffic + low time, high bounce, high support-ticket attachment, etc.), (2) the most likely root cause given the signal, (3) suggested intervention (rewrite / split per Diataxis / add troubleshooting / deprecate + redirect / leave + monitor), (4) effort estimate (S/M/L), (5) the metric you'd watch to confirm the fix worked. Do not propose work on pages with insufficient data — flag them as 'measure more'. CSV: [PASTE] ```

**Why it works:** Most doc-debt lists are written from the writer's frustration with a page, not from user-behavior data. Forcing a signal-to-intervention chain keeps the work honest — every proposed rewrite has a number behind it and a number to validate against. The 'insufficient data' flag is the discipline that stops 80%-of-traffic-from-2 pages teams from spending a sprint polishing the long tail.

**Sample output (condensed):** '| Rank | URL | Signal | Cause | Fix | Effort | Watch |\n| 1 | /docs/webhooks/signing | 18K views, 22s avg, 47 support tickets | Code sample broken in v4 | Rewrite with current SDK + add troubleshooting | M | support tickets / week |\n| 2 | /docs/quickstart | 41K views, 78% bounce | Diataxis-mixed; reads like reference | Split into tutorial + reference | L | activation rate D1 |\n| 3 | /docs/api/errors | 9K views, high internal-search landings | Errors not listed alphabetically | Re-sort + add filter | S | search-zero-result rate |\n| 14 | /docs/legacy/v2 | <50 views/mo | Stale, traffic gone | Deprecate + redirect to v4 | S | 404 rate |\n| 15 | /docs/changelog | insufficient data | (no time-on-page captured) | Measure more |'

Without these prompts: tech writers context-switch between OpenAPI specs, Slack threads, git logs, and analytics dashboards trying to keep docs in lockstep with a shipping product — and lose.
With these prompts: Claude becomes the structural co-writer that takes the spec, the log, the analytics export, and the messy draft, and hands back something a senior tech writer can sharpen in 30 minutes instead of a day.