Prompting for Documentation
Documentation That Developers Actually Read
Documentation is the task developers hate writing most and AI is arguably best at -- when prompted correctly. The problem with most AI-generated documentation is that it is verbose, generic, and reads like it was written by someone who has never used the code. Good documentation prompts produce output that is concise, specific, and written from the perspective of someone who needs to use the code right now.
The key insight is that different types of documentation serve different audiences and require different prompts. An API reference needs precision and completeness. A README needs clarity and quick-start instructions. Inline code comments need brevity and context. A changelog needs accuracy and relevance. Each type requires a different prompting approach.
API Documentation
API documentation needs to be precise, structured, and example-driven. The best approach is to let the AI read your actual route handlers and generate docs from the source code.
Generate REST API documentation for the user endpoints in src/routes/users.ts.
For each endpoint, document:
- HTTP method and URL (with path parameters)
- Description (one sentence: what it does)
- Authentication requirement (which endpoints require JWT?)
- Request body schema (with types and validation rules)
- Response body schema (with example JSON)
- Error responses (status code, error format, when it occurs)
- Rate limiting (if applicable)
Format as Markdown with code blocks for request/response examples.
Use our existing API docs in docs/api/products.md as the style reference.
For request/response examples, use realistic data (not "string" or "example").
OpenAPI/Swagger Generation
Generate an OpenAPI 3.0 specification in YAML for the authentication
endpoints in src/routes/auth.ts.
Endpoints to document:
- POST /api/auth/register
- POST /api/auth/login
- POST /api/auth/refresh
- POST /api/auth/logout
- GET /api/auth/me
For each endpoint, include:
- operationId (camelCase, descriptive)
- summary and description
- requestBody with JSON schema (derive from the Zod validation schemas in the code)
- responses for success and all error cases
- security requirements (which endpoints need the Bearer token?)
Use $ref for shared schemas: UserResponse, AuthTokens, ErrorResponse.
Include the components/schemas section at the bottom.
Reference the Zod schemas in src/schemas/auth.ts for exact field types and
validation rules.
README Generation
README files need to answer five questions quickly: What is this? How do I install it? How do I use it? How do I contribute? Where do I get help?
Create a README.md for our Express.js API project.
Project context:
- E-commerce REST API built with Express.js, TypeScript, Prisma, PostgreSQL
- Runs in Docker for development, deployed to AWS ECS in production
- 45 endpoints across 8 resource types (users, products, orders, etc.)
- Uses JWT authentication with refresh tokens
Sections to include:
1. Project title and one-paragraph description
2. Prerequisites (Node 20+, Docker, PostgreSQL 15)
3. Quick start (clone, install, setup env, run with Docker)
4. Environment variables (list them from .env.example with descriptions)
5. API overview (table of main resource endpoints, no full docs)
6. Development (how to run tests, lint, format, migrations)
7. Deployment (brief overview, link to separate deploy docs)
8. Contributing (link to CONTRIBUTING.md)
Style rules:
- Use code blocks for all commands
- Keep each section under 10 lines (link to detailed docs for more)
- Use a table for environment variables
- Do not include badges or shields (we will add those later)
Inline Code Documentation
Inline documentation -- JSDoc, docstrings, code comments -- needs to be concise and informative. The AI should add documentation that provides value beyond what the code itself communicates.
Bad prompt:
Add comments to this file
This produces comments like // increment counter above counter++, which add no value.
Good prompt:
Add JSDoc documentation to the public methods in src/services/OrderService.ts.
Rules:
- Only document public methods (skip private helpers)
- First line: what the method does in one sentence
- @param: type and description for each parameter
- @returns: what the method returns, including possible null/undefined
- @throws: list each error type and when it is thrown
- @example: include a usage example for complex methods
- Do NOT add comments to method bodies (the code is clear enough)
- Do NOT add obvious documentation (skip getters/setters with self-explanatory names)
Style reference: Follow the JSDoc patterns in src/services/UserService.ts.
Focus on documenting the "why" and edge cases, not the "what" that is obvious
from the function signature.
The "Explain to a New Team Member" Pattern
For architectural documentation that explains how pieces fit together:
Write a technical overview of our authentication system as if explaining it
to a developer who just joined the team.
Cover:
1. How the auth flow works (login -> JWT issuance -> token refresh -> logout)
2. Which files are involved (list each with a one-line description)
3. How middleware protects routes (authMiddleware, roleMiddleware)
4. How tokens are stored (httpOnly cookies? localStorage? both?)
5. How refresh tokens work and when they expire
6. Common gotchas new developers hit (CORS issues, token expiry during dev)
The reader is a mid-level developer who knows Express.js and JWT concepts
but has never seen our specific implementation.
Keep it under 500 words. Use code references (file paths, function names)
but do not include full code blocks. This is a map, not a tutorial.
Technical Writing Style Specification
When generating any documentation, specifying the writing style prevents the AI from producing bloated, corporate-sounding prose.
Style requirements for all documentation in this session:
- Write in active voice ("The function returns" not "The value is returned by")
- Use second person ("you" not "the user" or "one")
- Keep paragraphs under 4 sentences
- Include code examples for every concept (show, don't just tell)
- Use "Note:" for important caveats instead of embedding them in paragraphs
- Avoid words: "leverage", "utilize", "facilitate", "robust", "seamless"
- Prefer short words over long ones ("use" not "utilize", "start" not "initialize")
- Be direct: "This fails when X" not "It should be noted that in certain
circumstances, this may potentially fail when X"
You can include this style block at the beginning of a documentation session and reference it for all subsequent prompts.
Documentation From Code
One of the most useful documentation prompts asks the AI to explain existing code for documentation purposes.
Explain what the src/middleware/rateLimit.ts module does and how it connects
to the rest of the system.
Format:
1. One-paragraph summary (what it does and why it exists)
2. How it works (step by step, no code, just logic)
3. Configuration (what environment variables or options control its behavior)
4. Dependencies (what other modules it imports and why)
5. Where it is used (which routes or middleware chains include it)
6. Failure modes (what happens when Redis is down? when limits are exceeded?)
Write this as documentation for the docs/middleware/ directory. The audience
is a developer who needs to understand the rate limiter to either modify it
or debug a rate-limiting issue in production.
Changelog Generation
AI can generate changelog entries from git commits, but you need to specify the audience and level of detail.
Generate a changelog entry for version 2.4.0 from these commits:
[paste git log output or list of commit messages]
Format: Keep a Changelog (keepachangelog.com) format with sections:
- Added (new features)
- Changed (changes to existing functionality)
- Fixed (bug fixes)
- Deprecated (features to be removed)
- Security (security-related changes)
Rules:
- Write for end users and API consumers, not developers
- Each entry is one sentence, starting with a verb
- Group related commits into a single entry
- Skip internal refactoring, test changes, and CI updates
- Include the PR number in parentheses if available
- Highlight breaking changes with **BREAKING:** prefix
- For API changes, mention the specific endpoints affected
Migration Guides
When you release breaking changes, AI can help generate migration guides:
Generate a migration guide for users upgrading from v2.x to v3.0 of our API.
Breaking changes:
1. Authentication: Bearer token header changed from "X-Auth-Token" to
"Authorization: Bearer <token>"
2. Pagination: Changed from offset-based (?page=2&limit=20) to cursor-based
(?cursor=abc&limit=20)
3. Response format: Wrapped all responses in { data: ..., meta: ... } envelope
4. Removed endpoints: DELETE /api/users/:id/sessions (use POST /api/auth/logout)
For each change:
- Explain what changed and why
- Show the old way (v2) and the new way (v3) side by side
- Provide a code example showing the migration
- Note any edge cases or gotchas
Audience: developers who integrate with our API. They are busy and want to
migrate quickly. Be concise and practical -- they do not care about our
internal reasons, just what they need to change.
The Documentation Review Prompt
After generating documentation, review it for accuracy and completeness:
Review the API documentation in docs/api/orders.md against the actual
implementation in src/routes/orders.ts.
Check for:
1. Missing endpoints (any routes in the code that are not documented?)
2. Incorrect request/response schemas (does the doc match the actual Zod
validation and Prisma response?)
3. Missing error responses (are all error paths documented?)
4. Outdated examples (do the example requests actually work against current code?)
5. Missing authentication requirements (which endpoints need auth but do not
say so in the docs?)
For each discrepancy, show the doc text vs the actual code behavior.
This prompt catches the most common documentation problem: docs that were accurate when written but have drifted from the implementation. Running this prompt periodically keeps your documentation honest.