Create or revise [DOCUMENT TYPE] for [TARGET AUDIENCE]. The task the reader needs to complete is: [READER GOAL]. Use this source material as the authority: [SOURCE MATERIAL]. The product, environment, versions, prerequisites, and known limitations are: [TECHNICAL CONTEXT]. Match this tone and documentation standard: [STYLE AND FORMAT RULES]. Produce a publication-ready draft with this structure: purpose and scope; prerequisites; numbered procedure or concept explanation; expected result; validation steps; troubleshooting or limitations; and related references or open questions. Use headings that describe the reader’s task, imperative verbs for actions, and code blocks only for commands, configuration, or literal output. Preserve the meaning of the source material. Do not invent APIs, parameters, defaults, compatibility claims, performance figures, error messages, security behavior, links, or steps. When a fact is absent, mark it as “Needs confirmation” or write a narrowly worded placeholder rather than filling the gap. Separate a verified outcome from an example outcome. For each action, include the input, where to perform it, what success looks like, and a recovery action when the source supports one.
If the source includes a destructive, privileged, security-sensitive, or production action, put a visible warning immediately before that action and state the precondition or rollback information available in the source. Keep terminology consistent with the supplied product names and UI labels.
Ask up to 3 clarifying questions only if a required input is missing. Before answering, self-check that every procedural step is supported by [SOURCE MATERIAL], and flag any ambiguity that could cause data loss, security exposure, or an incorrect result.Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [DOCUMENT TYPE] | Enter the type of document, such as setup guide, API reference, runbook, or release note. | Setup guide |
| [TARGET AUDIENCE] | Describe the reader’s role and relevant technical knowledge. | Backend developers who know Docker but are new to the company’s local development environment |
| [READER GOAL] | State the concrete result the reader needs to achieve. | Run the billing API and its PostgreSQL dependency locally, then execute the health check |
| [SOURCE MATERIAL] | Paste the authoritative notes, existing draft, specifications, logs, or approved references. | Approved notes: copy .env.example to .env; set BILLING_API_KEY from the development vault; run docker compose up db; run npm install; run npm run dev; visit GET /health. Known error: port 5432 may already be in use; stop the local PostgreSQL service or change POSTGRES_PORT. |
| [TECHNICAL CONTEXT] | List product versions, environment, prerequisites, assumptions, and known limitations. | macOS or Linux; Node 22; Docker Desktop; development environment only; do not use production API keys. |
| [STYLE AND FORMAT RULES] | Describe the required tone, template, terminology, length, and formatting conventions. | Markdown, concise internal engineering docs, sentence-case headings, commands in fenced shell blocks, include a security warning for credentials. |
How to use
- Paste the approved source notes or the exact draft you want revised, then name the reader’s task.
- Check every command, version, UI label, and expected result against the authoritative source.
- Have the intended reader perform the procedure from a clean environment before publishing it.
- Follow up with: “Create a reviewer checklist that maps each step in this guide to the source statement that supports it.”
Variations
API reference
Use when documenting an endpoint without making up contract details.
Write API reference documentation for [ENDPOINT OR OPERATION] for [AUDIENCE] using only [AUTHORITATIVE SPEC]. Include purpose, authentication only if specified, method and path, parameters, request example, response fields, response examples, errors, limits, and version notes. Mark absent contract details as Needs confirmation; do not infer defaults from naming. Distinguish required from optional fields exactly as the source does. Before answering, verify every example matches the supplied schema. Ask up to 3 questions only if a required input is missing.
Troubleshooting guide
Use when users need a safe path through a known failure.
Create a troubleshooting guide for [PROBLEM] affecting [SYSTEM AND AUDIENCE]. Use these verified symptoms, causes, diagnostics, and fixes: [SOURCE NOTES]. Structure it as symptom, likely causes in safe diagnostic order, exact checks, resolution, and escalation criteria. Put destructive or permission-changing steps behind a warning and do not claim a cause is confirmed unless the diagnostic proves it. Include what logs or screenshots to collect before escalation. Ask up to 3 questions only if essential source details are missing.
Release notes
Use when translating approved changes into user-facing release notes.
Write release notes for [RELEASE NAME OR VERSION] for [AUDIENCE] from [APPROVED CHANGELOG]. Produce a short overview, Added, Changed, Fixed, Deprecated, and Known issues sections, omitting empty sections. Describe user-visible impact and required action; do not convert internal implementation details into unsupported customer promises. Preserve exact product names, dates, rollout limits, and compatibility conditions. Flag any item that lacks audience impact or approval for publication. Ask up to 3 questions only if required release context is missing.
Tips
- Treat source notes as evidence, not inspiration; if a parameter or recovery step is missing, label the gap instead of guessing.
- Write procedures in the order a reader can execute them, including prerequisites before the first command that depends on them.
- Pair each success criterion with a verification action so readers can tell a completed step from a command that merely exited.
- Place warnings directly before the risky command or action, not in a generic caution section readers may skip.
FAQ
Can AI safely rewrite technical documentation?
Yes, when it is constrained to authoritative source material and allowed to flag gaps. It should not fill missing product behavior with plausible-sounding details.
How do I keep generated commands accurate?
Supply the exact command, environment, and version notes, then run the finished procedure in a representative environment. Treat examples as code that needs testing.
Should troubleshooting steps include every possible cause?
No. Start with supported, high-probability checks in a safe order and state when the reader should escalate rather than experimenting with risky changes.