Code-to-Documentation Draft

The Prompt

You are a technical writer with strong {{language}} engineering experience. Convert the source context into a clear first draft of {{doc_type}} for {{target_audience}}.

Code and context:
{{code_context}}

Known limitations and caveats:
{{known_limitations}}

Return output with these sections only:
1) Overview (purpose and scope)
2) Architecture or flow (key components and interactions)
3) Setup or prerequisites
4) Usage guide (happy path first, then important alternatives)
5) Error handling and troubleshooting
6) Pitfalls and gotchas
7) FAQ (5-8 practical questions)
8) Open questions for maintainers

Constraints:
- Explain behavior from code evidence; mark assumptions explicitly.
- Prefer concise, copy-paste-ready examples.
- Avoid marketing language.
- Keep tone practical for day-to-day engineering use.
- Flag outdated or ambiguous parts of code comments when seen.

When to Use

Use this when you have code but poor docs, or when onboarding friction is high because important details only exist in implementation files. It works for internal tools, services, SDKs, and shared libraries.

Ideal scenarios:

• New maintainers need a fast understanding of an unfamiliar module
• Existing docs are stale after recent refactors
• You need a first-pass README or runbook from source code
• Teams require consistent documentation quality before release

This prompt is intentionally structured so the output can be dropped into project docs and then lightly edited by an engineer.

Variables

Variable	Description	Good input examples
language	Primary code language	TypeScript, Python, Rust
code_context	Relevant files, snippets, architecture notes	Main module + config + sample usage
target_audience	Who will read the docs	”new backend engineers”, “platform on-call team”
doc_type	Documentation format or goal	README, runbook, API integration guide
known_limitations	Current constraints and unresolved issues	”No retries on webhook delivery”, “partial multi-region support”

Tips & Variations

• Ask for “short version and long version” if you need both README and deep docs.
• Add “include Mermaid diagram” when architecture visualization is useful.
• Add repository conventions, such as coding standards or release steps, to improve team alignment.
• For incident-heavy systems, request an expanded troubleshooting decision tree.
• After output, run a follow-up prompt: “Turn open questions into TODO issues.”

To keep output accurate, include real code snippets and configuration details instead of only high-level summaries.

Example Output

Overview: This service ingests webhook events, normalizes payloads, and writes idempotent records to the events table.

Pitfall: Retries are disabled for downstream timeouts; failed deliveries require manual replay.

FAQ: “How do I run this locally without external webhooks?” includes a local fixture replay command.