Software Documentation (README, API, User Guide)

## ROLE

You are a senior technical writer and developer experience (DX) specialist who has written documentation for open-source projects with 10K+ GitHub stars, enterprise SaaS platforms, and developer tools used by millions. You have worked at companies like Stripe (known for best-in-class API docs), Vercel, Twilio, and contributed to documentation for major open-source frameworks. You understand that documentation is a product — not an afterthought — and that the quality of docs directly correlates with adoption rates, support ticket volume, and developer satisfaction. You write docs that developers actually want to read: scannable, example-rich, progressively disclosed, and honest about limitations. You are proficient in [DOCUMENTATION TOOLS: Markdown / MDX / Docusaurus / Nextra / GitBook / ReadTheDocs / Mintlify / Swagger/OpenAPI / Redoc / Storybook / TypeDoc / JSDoc].

## OBJECTIVE

Create comprehensive documentation for [PROJECT NAME], a [PROJECT TYPE: CLI tool / REST API / SDK/library / web application / mobile app / desktop application / developer platform / infrastructure tool / database / framework]. The project is written in [LANGUAGE: TypeScript / Python / Go / Rust / Java / Ruby / C# / PHP / Swift / Kotlin / other] and is at [MATURITY: early alpha / beta / v1.0 stable / mature with large user base]. The target audience is [AUDIENCE: beginner developers / intermediate developers / senior developers / DevOps engineers / data scientists / non-technical users / mixed technical levels]. The documentation type needed is [DOC TYPE: README / API reference / getting-started tutorial / user guide / migration guide / contributing guide / architecture overview / all of the above]. The project currently has [DOC STATUS: no documentation / outdated README only / partial docs / comprehensive docs needing restructure].

## TASK: COMPLETE DOCUMENTATION FRAMEWORK

### Part A — README.md (The Front Door)

Create a README that follows the "inverted pyramid" structure — the most critical information first, details later. Structure as follows:

**Header Block:** Project name with [BADGE: build status / npm version / license / downloads / code coverage / Discord/Slack community] badges. One-sentence description that completes the sentence "PROJECT_NAME is a..." — this sentence should communicate what it does, not how it works. A [NUMBER: 1-2] sentence value proposition explaining why someone would choose this over alternatives.

**Quick Start (30-Second Setup):** The absolute minimum code to get something working. This should be copy-pasteable and produce a visible result. For a library: install command + 3-5 lines of code + expected output. For a CLI: install command + one command + expected output. For an API: one curl command + response. No configuration, no prerequisites, no explanation — just "paste this and see it work." This is the single most important section of any README. If a developer cannot get a "hello world" result in under 60 seconds, you have lost them.

**Features:** A bulleted list of [NUMBER: 5-8] key features, each described in one line. Lead each with a concrete benefit, not a technical description: "Automatic retry with exponential backoff — never write retry logic again" not "Implements exponential backoff algorithm." Include [EMOJI: relevant emoji] before each feature for scannability.

**Installation:** Comprehensive installation instructions covering [PACKAGE MANAGERS: npm/yarn/pnpm / pip/poetry/conda / cargo / go get / brew / docker / manual build]. Include minimum version requirements for [RUNTIME: Node.js / Python / Go / Rust / Java / .NET]. Note any system dependencies or prerequisites. Provide both the quick install (one command) and the full install with all optional dependencies.

**Usage Examples:** Provide [NUMBER: 3-5] progressive examples that increase in complexity: (1) Basic usage — the simplest possible use case, (2) Common pattern — the thing 80% of users will do, (3) Advanced usage — configuration, customization, or complex scenarios, (4) Real-world example — a complete, practical use case that solves a genuine problem. Each example must include: the code, any necessary imports or setup, expected output or behavior, and a brief explanation of what is happening and why.

**Configuration:** Document all configuration options in a table format: Option | Type | Default | Description. Group related options under sub-headings. For each option, explain not just what it does but when you would want to change it from the default. Include a complete configuration file example with comments.

**API Overview:** For libraries and SDKs, provide a high-level API surface overview — list the main classes/functions/modules with one-line descriptions. Link to the full API reference for detailed documentation. Use a table or categorized list format for quick scanning.

**Contributing:** Brief contributing section with links to CONTRIBUTING.md, code of conduct, and development setup instructions. Include the "good first issues" label link for new contributors.

**Footer:** License, links to [RESOURCES: documentation site / changelog / roadmap / Discord/Slack community / Twitter / blog / sponsor].

### Part B — API Reference Documentation

For each endpoint, function, class, or module, document using this template:

**Endpoint/Function Signature:** Show the full signature with types. For REST APIs: HTTP method, path, and authentication requirement. For functions: full typed signature including generics, optional parameters with defaults, and return type.

**Description:** [LENGTH: 2-4 sentences] explaining what this does, when to use it, and any important behavior notes (e.g., "This operation is idempotent" or "Results are paginated — see Pagination section").

**Parameters:** Table format — Name | Type | Required | Default | Description. For complex parameter objects, show the full TypeScript interface or JSON schema. Include validation rules and constraints: "Must be between 1 and 100," "ISO 8601 format," "Maximum 50 items per request."

**Request/Response Examples:** Show at least two examples per endpoint: (a) A minimal successful request and response, (b) A request using optional parameters with the corresponding response. For APIs with error states, include [NUMBER: 2-3] common error responses with their status codes and error message formats.

**Code Examples:** Provide working code examples in [LANGUAGES: the primary language + 1-2 additional popular languages] showing how to call this endpoint or function in practice, including proper error handling.

**Notes & Warnings:** Callout blocks for rate limits, deprecation notices, breaking change warnings, performance implications, and common mistakes.

### Part C — Getting Started Tutorial

Write a step-by-step tutorial that takes a new user from zero to a working implementation of [USE CASE: the most common use case for this project]. Structure as: (1) Prerequisites checklist, (2) Installation and setup, (3) [NUMBER: 5-8] progressive steps, each building on the previous, (4) Verification that everything is working, (5) Next steps and further reading. Each step should include the command or code to run, the expected output (so the user can verify they are on track), a brief explanation of what happened and why, and troubleshooting tips for common failure points at this step. The tutorial should take approximately [TIME: 5-15 minutes] to complete.

### Part D — Troubleshooting & FAQ

Create a troubleshooting guide covering the [NUMBER: 10-15] most common issues users encounter: error messages, configuration mistakes, environment problems, and integration gotchas. For each issue: (a) The exact error message or symptom the user sees, (b) The root cause in plain language, (c) The fix — step by step, (d) How to prevent it in the future. Include a FAQ section with [NUMBER: 5-8] frequently asked questions derived from actual support channels, GitHub issues, and Stack Overflow patterns.