Documentation is the thing everyone agrees is important and nobody wants to write. After building developer-facing products for two years, I've settled on an AI-assisted workflow that produces docs developers actually read — not the kind that sit in a /docs folder collecting virtual dust.
Here's the system, the prompts, and the constraints that make it work.
The Core Problem With AI-Generated Docs
Most people write documentation with AI like this: "Write docs for my API." The output is a 2,000-word wall of text with vague intros, redundant sections, and code examples that don't compile.
The fix is not better AI. It's better constraints. Every prompt below specifies the audience, the format, the word count, and — critically — what to exclude.
Step 1: Generate the Doc Structure First
Before writing any content, generate a table of contents that you can review and approve.
Role: You are a technical writer who creates documentation for developer
tools.
Context: I need documentation for [PRODUCT/FEATURE]. The audience is
[WHO — e.g., "backend developers integrating a payments API for the
first time"]. The product does [ONE-SENTENCE DESCRIPTION].
Constraints:
- Generate a documentation outline with maximum 8 top-level sections
- No section may have more than 3 subsections
- The first section must be a 5-minute quickstart, not an introduction
- The last section must be a troubleshooting/FAQ, not a conclusion
- Ban these section types: "Overview," "Introduction," "Conclusion,"
"About This Document"
- Each section title must be an action or a noun, not a gerund
(no "Getting Started" — use "Quickstart" instead)
Output: A numbered outline. For each section, write one sentence
explaining what it covers and why a developer would go there.
Why this works: The "quickstart first" constraint is the single most important rule in developer documentation. Developers don't read docs linearly — they scan for the thing that gets them to a working integration in under 10 minutes. If that doesn't exist, they leave.
Step 2: Write the Quickstart (The Only Section Developers Read)
Role: You are a developer advocate writing a quickstart guide.
Context: [PRODUCT] is a [TYPE]. The quickstart should get a developer
from zero to their first successful API call / first feature working.
Constraints:
- Maximum 400 words
- Structure: Prerequisites (bullet list) → Install (one command) →
Authenticate (one code block) → First Request (one code block) →
Expected Output (one code block) → Next Steps (3 links max)
- Every code block must be copy-pasteable and complete — no "// add
your code here" placeholders
- Prerequisites: list only things they MUST have, not nice-to-haves
- Ban "In this quickstart, we will..." — just start with Prerequisites
- The "First Request" code block must produce visible output in
under 30 seconds of execution
Output: The complete quickstart in Markdown. Include the language
label for each code block.
Why this works: The copy-pasteable constraint kills the most common documentation failure: code examples that are fragments. If a developer has to fill in blanks, the quickstart isn't a quickstart — it's a puzzle.
Step 3: Write API Reference Entries (Consistent, Not Comprehensive)
Role: You are a technical writer producing API reference documentation.
Context: Here is the endpoint/function: [NAME, METHOD, PATH].
Parameters: [LIST]. Returns: [DESCRIPTION]. Error cases: [LIST].
Constraints:
- For each endpoint, produce exactly this structure:
1. One-line description (what it does, not what it is)
2. Request example (complete, copy-pasteable)
3. Parameter table: name | type | required | description | default
4. Success response example
5. Error response table: status code | meaning | how to fix
- Description in the parameter table: maximum 15 words per parameter
- The "how to fix" column must be actionable, not "check your request"
- If a parameter is optional, explain what happens if omitted
- Ban "This endpoint allows you to..." — start with a verb
Output: Markdown reference entry following the 5-part structure above.
Why this works: API reference docs fail when they're inconsistent — one endpoint has a parameter table, another doesn't; one has error examples, another doesn't. This prompt enforces a rigid template so every entry looks the same, which is what developers actually want from reference material.
Step 4: Write the Troubleshooting Section
Role: You are a support engineer who writes troubleshooting guides
based on real ticket data.
Context: These are the top issues users report with [PRODUCT]:
[LIST 5-8 COMMON ISSUES from support tickets, GitHub issues, or
community forums].
Constraints:
- For each issue, create a troubleshooting entry with this structure:
Symptom (what the user sees) → Likely Cause → Fix (numbered steps)
- Each entry: maximum 100 words
- The "Fix" must be specific steps, not "check your configuration"
- If a fix requires changing code, include the exact code to change
- Order entries from most common to least common
- Ban "Please contact support" as a fix — if the issue genuinely
requires support, say "This may require support intervention" and
explain what information to include in the ticket
Output: Numbered troubleshooting entries, each with the 3-part structure.
Why this works: Troubleshooting docs are usually written speculatively — "here are things that might go wrong." This prompt forces you to start from real support data. The 100-word cap per entry prevents the rambling explanations that make troubleshooting pages unreadable.
Step 5: Write the Migration Guide (When You Break Things)
Role: You are a developer relations engineer writing a migration guide
for a breaking change.
Context: We are changing [WHAT'S CHANGING] on [DATE]. Old behavior:
[OLD]. New behavior: [NEW]. Users who don't migrate will experience
[CONSEQUENCE].
Constraints:
- Structure: What's Changing (2 sentences) → Who's Affected (1 sentence)
→ Migration Steps (numbered) → Code Before/After (side by side)
→ Timeline (dates)
- Migration steps: maximum 7 steps
- Each step must be independently testable (include how to verify)
- The "Code Before/After" must show the exact diff, not a rewrite
- If the migration is optional, say so in the first line
- Ban "We're excited to announce" — developers don't care about your
excitement, they care about what breaks
Output: Complete migration guide in Markdown.
Why this works: Migration guides are the highest-stakes documentation — get them wrong and you break production for your users. The "independently testable steps" constraint means a developer can verify each step before moving to the next, instead of doing all 7 steps and hoping nothing exploded.
Step 6: Write the Architecture Decision Record (ADR)
Role: You are a staff engineer who writes ADRs for a engineering team.
Context: Decision needed: [DESCRIBE THE TECHNICAL DECISION]. Options
being considered: [LIST 3-4 OPTIONS]. Constraints: [BUDGET/TEAM/
TIMELINE/TECHNICAL CONSTRAINTS].
Constraints:
- Use this ADR structure:
1. Context (what problem are we solving) — 3 sentences max
2. Decision (what we chose) — 1 sentence
3. Status (proposed/accepted/superseded) — 1 word
4. Alternatives Considered — for EACH alternative, 3 sentences:
when it would be the right choice, why we rejected it, and the
trigger that would make us revisit it
5. Consequences (positive and negative) — bullet list
- Ban "We decided to go with" — use "Decision: [CHOICE]"
- Each alternative must be treated fairly — no strawman rejections
- The "trigger to revisit" is mandatory for every rejected option
Output: ADR in Markdown following the 5-part structure.
Why this works: The "trigger to revisit" constraint is the secret weapon of good ADRs. Without it, rejected alternatives disappear and the team re-litigates the same decision 6 months later because nobody remembers why Option B was rejected. With it, the ADR becomes a living document that prevents circular arguments.
Step 7: Review and Cut
This is a prompt I run after generating all the sections:
Role: You are a ruthless documentation editor.
Context: Here is the documentation I generated: [PASTE ALL SECTIONS].
Constraints:
- Identify and list any sentence that could be deleted without losing
information. Label each as "REDUNDANT" with a reason.
- Identify any code example that is not copy-pasteable. Label as
"INCOMPLETE CODE."
- Identify any instruction that is vague ("configure appropriately,"
"set up your environment"). Label as "VAGUE."
- Identify any section longer than 300 words. Label as "TOO LONG"
and suggest where to split it.
- Do NOT rewrite anything. Only flag issues.
Output: A numbered list of issues found, each with the label, the
specific text, and the reason.
Why this works: AI-generated docs overproduce. This review prompt catches the three most common failure modes — redundancy, incomplete code, and vagueness — without you having to read every word manually. Run it, fix the flagged issues, and your docs are production-ready.
The Workflow in Practice
Here's how I run this end-to-end for a new feature:
- Generate the outline (Step 1), review it, cut sections that don't serve the audience
- Write the quickstart (Step 2) — this is 80% of the value
- Write API reference entries (Step 3) for each endpoint/function
- Write troubleshooting (Step 4) from real support data
- Skip migration guide (Step 5) unless it's a breaking change
- Write an ADR (Step 6) for any non-obvious technical decision
- Run the review prompt (Step 7), fix flagged issues
Total time for a mid-size feature: about 90 minutes. Before this workflow, the same docs took a full day and were lower quality.
Common Mistakes to Avoid
Don't generate all sections in one prompt. The outline-first approach lets you course-correct before you've invested in content. Generating everything at once produces a 5,000-word document that's wrong in its structure.
Don't skip the review step. The review prompt (Step 7) catches issues that compound — one vague instruction in a quickstart cascades into a broken integration.
Don't let AI choose the examples. Always provide the actual code examples yourself and ask AI to document them. AI-generated code examples compile about 60% of the time in my testing; your real code compiles 100% of the time.
Take These Prompts and Adapt Them
Every prompt above uses the same structure: Role → Context → Constraints → Output. The constraints are where the value is. Copy the framework, fill in your product details, and adjust the constraints to match your documentation style guide.
The goal is not perfect AI output on the first try. It's output that's 80% correct, which you then review and ship in a fraction of the time it would take to write from scratch.
Looking for more AI workflows like this? I've compiled a library of prompts for documentation, engineering management, product, and marketing — each tested the same way. The full prompt pack is here.
For teams that need a complete system, the AI Startup Operations Prompt System includes 50+ prompts with full workflow documentation, covering engineering, product, and operations.
Top comments (0)