Technical Documentation
Turn code comments and architecture decisions into documentation the rest of the team can follow.
What you'll need
- Source code files
- Architecture decision records (ADRs)
- API endpoints
- Database schemas
- Existing docs (to update vs. create)
Put it to work
Save these instructions in a Claude Skill or Project, or in a ChatGPT Project or Custom GPT. Add your context, run the sample prompt, and check the result against your team's standards before anyone relies on it.
Reusable playbook
Learn the method, adapt the details, then put it to work.
Start here
Reusable instruction — Claude: save as a skill file at ~/.claude/skills/product/technical-docs.md · ChatGPT: paste into a Custom GPT's instructions or a Project.
Give the AI a clear role
You are a technical writer who makes complex systems understandable to developers.
Bring the right context
- {{existing_docs_path}} - Existing documentation (optional)
- {{adrs_path}} - Architecture decision records (optional)
- Source code files
- Architecture decision records (ADRs)
- API endpoints
- Database schemas
- Target audience description
Run the method
Given source code and architecture context
- 1
System Understanding
- Identify core components
- Map dependencies
- Note design patterns used
- Find entry points
- 1
Documentation Structure
- Overview and purpose
- Getting started
- Architecture guide
- API reference
- Troubleshooting
- 1
Content Generation
- Clear explanations (not just code rewrites)
- Working examples
- Common pitfalls
- Decision rationale
04Preview the deliverableSee the shape of a strong answer before you run the workflow.
[Component/System Name]
Overview
[2-3 sentences on what this is and why it exists]
Quick Start
Installation
npm install [package]
Basic usage
[minimal code example]
Architecture
System Diagram
[ASCII diagram or mermaid syntax]
Components
- Component
- [Name]
- Purpose
- [What it does]
- Key Files
- path/to/file.ts
| Component | Purpose | Key Files |
|---|---|---|
| [Name] | [What it does] | path/to/file.ts |
Data Flow
- 1
[Step 1]
- 2
[Step 2]
- 3
[Step 3]
API Reference
functionName(params)
[Description of what it does]
Parameters:
- Name
- param1
- Type
- string
- Required
- Yes
- Description
- [What it is]
| Name | Type | Required | Description |
|---|---|---|---|
| param1 | string | Yes | [What it is] |
Returns: ReturnType [Description of return value]
Example: // Example usage const result = functionName('value');
Errors:
| Error | Cause | Resolution |
|---|
Configuration
| Option | Type | Default | Description |
|---|
Troubleshooting
[Common Issue 1]
Symptom: [What you see] Cause: [Why it happens] Fix: [What to do]
Design Decisions
Why [Decision]?
[Explanation of the tradeoff and rationale]
Try this prompt
Create documentation for our authentication module: Files: - /src/auth/index.ts (main entry) - /src/auth/strategies/* (OAuth, SAML, passwordless) - /src/auth/middleware.ts (Express middleware) - /src/auth/types.ts (TypeScript interfaces) Cover: 1. How to add auth to a new route 2. How to configure each auth strategy 3. How the token refresh flow works 4. Common setup mistakes Target audience: New developers joining the team.
Before you trust the output
- Include real, working examples
- Explain "why" not just "what"
- Keep docs next to code (easier to update)
Your next step
Want this workflow to run reliably every week?
Bring Technical Documentation to our free live workshop. We'll show you how to turn the reusable instructions into a working AI Agent Skill—without writing code.