Technical writing is one of the highest-value applications for AI — it requires precision, clarity, and consistency at scale. AI dramatically accelerates documentation production while requiring careful human review for accuracy.

1. API Documentation

OpenAPI Spec from Code

Prompt: Generate an OpenAPI 3.1 specification for this API endpoint.

Endpoint: POST /api/v1/payments/refund
Language: TypeScript (Express.js)
Authentication: Bearer token (JWT)

Request body TypeScript type:
interface RefundRequest {
  paymentId: string;        // UUID of original payment
  amount?: number;          // Optional: partial refund amount in cents. If omitted, full refund
  reason: 'duplicate' | 'fraudulent' | 'requested_by_customer' | 'other';
  notes?: string;           // Optional: internal notes, max 500 chars
}

Response types:
interface RefundResponse {
  id: string;               // UUID of the refund
  paymentId: string;        // Original payment ID
  amount: number;           // Refunded amount in cents
  status: 'pending' | 'succeeded' | 'failed';
  createdAt: string;        // ISO 8601 timestamp
  estimatedArrival?: string; // ISO 8601, only when status is 'pending'
}

Possible errors:
- 400: Invalid request (missing required fields, invalid amount)
- 404: Payment not found
- 409: Payment already refunded
- 422: Refund amount exceeds original payment amount

Generate a complete OpenAPI 3.1 path object with:
- Operation ID
- Tags
- Summary and description
- Security scheme reference
- Request body with examples
- All response codes with schemas and examples

Method Documentation

Prompt: Write documentation for this function.

Language: Python
Style: Google docstring format
Target audience: Senior engineers, not beginners

Function:
def calculate_adjusted_close_price(
    raw_close: float,
    split_factor: float,
    dividend: float,
    previous_close: float,
) -> float:
    """
    TODO: Add docstring
    """
    adjustment_factor = (previous_close - dividend) / previous_close
    return (raw_close * adjustment_factor) / split_factor

Context:
- Used in financial data processing pipeline
- Applies corporate action adjustments to stock price data
- Called for each trading day going backwards through historical data
- split_factor: ratio from stock splits (e.g., 2.0 for 2:1 split)
- dividend: per-share dividend amount in same currency as price
- previous_close: closing price before the corporate action date

Write a docstring that:
- Explains the financial concept (why adjustment is needed)
- Documents each parameter precisely (type, units, valid range)
- Explains the return value
- Includes the formula being applied
- Notes any assumptions or edge cases
- Includes 2-3 realistic examples

2. README Files

Project README

Prompt: Write a comprehensive README for this open-source project.

Project: A TypeScript library called "rate-limiter-flex"
What it does: Flexible rate limiting for Node.js applications with 
support for multiple storage backends
Key features:
- Redis and in-memory backends
- Fixed window, sliding window, and token bucket algorithms
- TypeScript first with full type safety
- Express, Fastify, and Koa middleware included
- Custom key extractors (IP, user ID, API key)
- Async-friendly with Promise API
- Zero dependencies (except Redis client, which is optional)
Target audience: Backend JavaScript/TypeScript developers
License: MIT
GitHub: https://github.com/example/rate-limiter-flex

README structure:
1. Header with badges (npm version, tests, coverage, license)
2. Overview paragraph (what problem does it solve, who should use it)
3. Features list (bullet points with brief explanation each)
4. Installation (npm, pnpm, yarn)
5. Quick Start (working example in 20 lines or less)
6. Usage (3-4 examples covering: Redis backend, in-memory, Express middleware, custom key)
7. API reference (main classes and methods)
8. Configuration options (table format: option, type, default, description)
9. Contributing (brief)
10. License

Code examples should be complete and runnable.

CHANGELOG

Prompt: Write a CHANGELOG entry for this release.

Version: 2.4.0
Release date: 2026-02-12

Changes in this release:
New features:
- Added support for PostgreSQL backend (in addition to Redis and in-memory)
- New `RateLimiter.reset(key)` method to manually reset a counter
- Token bucket algorithm now supports fractional rates (e.g., 1.5 requests/second)

Bug fixes:
- Fixed race condition in sliding window algorithm when Redis cluster is used
- Memory leak fixed when creating many rate limiters without cleanup
- TypeScript: `RateLimiterOptions.points` now correctly typed as number (was string)

Breaking changes:
- Minimum Node.js version bumped from 14 to 18
- `RateLimiter.consume()` now returns a `RateLimiterResponse` object instead of boolean
  - Before: `const allowed = await limiter.consume(key)` returned `true/false`
  - After: `const { success, remainingPoints } = await limiter.consume(key)`

Deprecations:
- `RateLimiter.set()` is deprecated — use `RateLimiter.reset()` instead
  - Will be removed in v3.0.0

Write using Keep a Changelog format:
https://keepachangelog.com/

3. User Guides and Tutorials

Getting Started Guide

Prompt: Write a Getting Started guide for our product.

Product: PostHog (self-hosted analytics platform)
Target user: Developer setting up PostHog for the first time
Assumed knowledge: Comfortable with Docker and command line
Time to complete: ~20 minutes

Guide sections:
1. What you'll build (concrete outcome)
2. Prerequisites (what they need before starting)
3. Installation (step-by-step, with exact commands)
4. First event capture (the "hello world" moment)
5. Setting up a dashboard (quick win to see value)
6. Next steps (where to go from here)

For each step:
- Exact commands (copy-pasteable)
- Expected output (what success looks like)
- Common errors and solutions
- Why this step matters (brief, optional context)

Style:
- Second person ("you")
- Numbered steps, not prose
- Code blocks for all commands
- Screenshots described as [Screenshot: X] placeholder
- Friendly but efficient (no padding)

Troubleshooting Guide

Prompt: Create a troubleshooting guide for common database connection issues.

Application: Node.js app connecting to PostgreSQL
Common errors to address:

Error 1: ECONNREFUSED 127.0.0.1:5432
Error 2: password authentication failed for user "postgres"
Error 3: SSL connection is required
Error 4: too many connections (max_connections reached)
Error 5: could not translate host name to address
Error 6: connection timeout (no error message, just hangs)

For each error:
1. What the error message looks like (exact text)
2. What causes it (1-2 sentences)
3. How to diagnose (specific commands to run)
4. Fix steps (ordered, numbered, specific)
5. Prevention (how to avoid it in future)

Format: Structured for scanning — headers, code blocks, not prose paragraphs
Target: Developer who got an error and needs fast resolution

4. Code Comments and Inline Documentation

Complex Algorithm Documentation

Prompt: Add comprehensive inline documentation to this algorithm.

The code implements the Aho-Corasick string matching algorithm.
Target audience: Software engineers who know algorithms but may not 
know this specific one.

[Paste the implementation]

Add:
1. Module-level docstring explaining: what the algorithm does, 
   time/space complexity, when to use it
2. Class-level documentation for the Trie structure
3. Method docstrings for all public methods (parameters, returns, complexity)
4. Inline comments at non-obvious steps explaining WHY (not what)
5. Complexity annotations at key loops

Rules:
- Don't document obvious things ("add i to the list")
- DO document why certain choices were made
- Reference the original paper if implementing academic algorithm
- Flag any known edge cases or limitations

5. Documentation Testing and QA

Checking Docs for Common Issues

Prompt: Review this documentation section for technical writing quality.

Section: [Paste your documentation]

Check for:
1. Accuracy (does the code example actually work as described?)
2. Completeness (are there undocumented parameters or edge cases?)
3. Clarity (would someone new to this understand it without prior context?)
4. Consistency (terms used consistently? formatting consistent?)
5. Actionability (can the reader take action from this documentation?)
6. Assumptions (does it assume knowledge the reader might not have?)

Also:
- Identify any jargon that should be explained or linked
- Flag passive voice that obscures who does what
- Find sentences that could be split for clarity
- Check that all code examples have context (what file, what imports)

Output: Specific issues with suggested fixes

Documentation Coverage Analysis

Prompt: Analyze this codebase's documentation coverage.

I'll provide the API surface (public methods and types):
[Paste your API reference]

And the existing documentation:
[Paste or describe your current docs]

Identify:
1. Public methods with no documentation
2. Parameters documented but not explained clearly
3. Methods where the "why" is missing (only "what" is documented)
4. Types and interfaces lacking documentation
5. Error conditions and edge cases not documented

Prioritize: Which gaps would most confuse a new user of this library?
Output: Prioritized list with recommended documentation for each gap

6. Localization-Ready Documentation

Writing for Translation

Prompt: Rewrite this documentation to be more translation-friendly.

Original text: [Paste documentation section]

Translation-friendly writing rules to apply:
1. Use simple sentences (subject-verb-object, max 25 words)
2. Avoid idioms and culturally-specific references ("piece of cake" → "simple")
3. Use active voice ("click the button" not "the button should be clicked")
4. Be explicit (don't use pronouns when noun is clearer)
5. Avoid humor that relies on wordplay
6. Use numbered steps instead of prose for sequences
7. Define acronyms on first use every time (even in same document)
8. Avoid double negatives
9. Use consistent terminology (don't vary the word for the same concept)
10. Break compound sentences into simple ones

Rewrite maintaining all technical accuracy while applying these rules.

7. Release Notes for Different Audiences

Prompt: Write release notes for the same update targeted at different audiences.

Update: We've improved our search feature with AI-powered semantic search

Technical changes made:
- Replaced keyword matching with vector embeddings (OpenAI text-embedding-3-small)
- Added approximate nearest neighbor search using pgvector
- Search latency: 45ms → 180ms average (trade-off for quality)
- Added spell correction and intent detection
- Search results now ranked by relevance score, not just recency

Write release notes for:

1. Engineering changelog (technical, specific):
   - Exact technology changes
   - Performance metrics
   - Known limitations
   - Migration notes if any

2. Product release notes (product teams, PMs):
   - What changed from user perspective
   - Business impact
   - Limitations
   - No implementation details

3. Marketing announcement (end users):
   - Benefits in plain English
   - Examples of how it helps
   - No technical details
   - Call to action

Each version should be complete and appropriate for that audience.

AI in technical writing works best when the human provides accurate technical context and the AI handles structure, clarity, and completeness checks. Always verify AI-generated code examples and technical claims before publishing.