Create technical documentation for [SYSTEM OR PROCESS] for [AUDIENCE]. The documentation must help them accomplish [USER GOAL] safely and consistently. Use only the material below as source of truth: [SOURCE NOTES]. Account for these environment details and constraints: [ENVIRONMENT AND CONSTRAINTS]. The documented owner and review cadence are [OWNER AND REVIEW CADENCE]. Produce a publishable document of 900 to 1,300 words with these sections, in this order: 1. Purpose, scope, and what this document does not cover. 2. Prerequisites: access, permissions, tools, versions, dependencies, and expected starting state. 3. Architecture or process overview: explain components, data flow, and ownership in plain language.
4. Numbered procedure: one action per step, exact command or UI path where supplied, expected result after meaningful steps, and a rollback or stop condition where relevant. 5. Validation: concrete checks that prove the goal was completed, including expected outputs or observable behavior. 6. Troubleshooting table with symptom, likely cause, safe first action, escalation owner, and information to collect before escalating. 7. Security, privacy, and change-control notes, limited to evidence in the source material. 8. Ownership, last-reviewed field, and a proposed review trigger. Use warning labels only for actual risks described in the notes. Never invent commands, API parameters, permissions, recovery steps, service-level commitments, or security controls. Mark missing operational details as “Needs confirmation” exactly where they matter. Before answering, verify that each procedure step has a prerequisite and a success check. Then flag any instruction that could cause data loss, production impact, or credential exposure without an explicit approval or backup step. Ask up to three clarifying questions only if a required input is missing.
Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [SYSTEM OR PROCESS] | Name the product, service, workflow, or integration being documented. | Salesforce-to-warehouse nightly account sync |
| [AUDIENCE] | Describe who will use the documentation and their technical level. | Data operations analysts who can use SQL but do not deploy services |
| [USER GOAL] | State the specific outcome the reader must achieve. | Verify the sync, diagnose a failed run, and escalate with the right evidence |
| [SOURCE NOTES] | Paste accurate notes, existing commands, links, decisions, and known issues. | Airflow DAG salesforce_accounts runs at 02:00 ET; success writes to analytics.crm_accounts; failures alert #data-ops; reruns require the data engineering on-call. |
| [ENVIRONMENT AND CONSTRAINTS] | Describe environments, versions, access limits, compliance rules, and production constraints. | Production is read-only for analysts; do not expose Salesforce tokens; warehouse tables contain customer contact data. |
| [OWNER AND REVIEW CADENCE] | Provide the accountable owner and how often or when the document should be reviewed. | Data Platform owns the DAG; review after any connector change and every six months. |
How to use
- Paste source notes that include actual commands, ownership, failure symptoms, and access restrictions.
- Replace bracketed inputs, then ask the model to draft the document.
- Verify every command and expected result in a non-production environment or against an experienced operator.
- Follow up with: “Turn the troubleshooting section into a two-column on-call quick reference without adding new procedures.”
Variations
API integration guide
Use when documenting how developers consume an internal or external API.
Write an API integration guide for [API NAME] for [DEVELOPER AUDIENCE], based only on [OFFICIAL API NOTES]. Cover authentication, base URLs by environment, required request fields, example requests using only supplied values, response handling, pagination or rate limits if documented, error codes, and a verification checklist. Clearly label placeholders and never create credentials, endpoints, schemas, or limits not in the source. Flag source contradictions and missing version information before the guide.
Incident runbook
Use for a repeatable response to a known production issue.
Create an incident runbook for [INCIDENT TYPE] from [KNOWN SIGNALS AND STEPS]. Produce an opening checklist, severity criteria, immediate containment actions, diagnostic sequence, communications cadence, escalation path, recovery validation, and post-incident evidence to retain. Each action must state who may perform it and whether approval is required. Do not invent recovery commands. Flag steps that could affect customers, data integrity, or security as requiring confirmation from [INCIDENT OWNER].
New-hire setup
Use to document access and equipment setup for a role.
Create a first-week setup guide for a new [ROLE] using [APPROVED SYSTEMS AND STEPS]. Organize it by day, include access request owners, prerequisites, expected confirmation, and where to get help. Separate mandatory access from optional tools. Do not include passwords, shared secrets, or instructions that bypass approval. End with a manager checklist showing what must be confirmed by [START DATE].
Tips
- Document the expected state after a step, not only the action; it gives readers a way to detect failure early.
- Put permissions and access requirements before the procedure, because readers otherwise discover blockers halfway through.
- A troubleshooting entry needs an escalation owner and evidence to collect, not just a list of possible causes.
- Treat documentation as a maintained operational asset: name the owner and review trigger in the document itself.
FAQ
Can AI write technical documentation from a code repository?
It can draft a useful structure from supplied code and notes, but an owner must validate commands, permissions, and production behavior before publication.
Should technical documentation include exact commands?
Include exact commands when they are verified and safe for the stated environment. Otherwise provide the approved path and mark the command as needing confirmation.
How long should a runbook be?
Long enough to carry out the task under pressure. A short overview plus numbered actions and a troubleshooting table is usually easier to use than a long narrative.