# Project Name

> One-line description of what this project does. 
> Who it's for and why it exists.

[Build Status] [Coverage] [Docs] [License]

## Quick Start

```bash
# Clone and install in under 30 seconds
git clone https://github.com/user/project.git
cd project
npm install
npm start

# Minimal working example — copy, paste, run
from my_library import Client

client = Client(api_key="your-key")
result = client.search("quantum computing")
print(result)

client = Client(api_key="sk-xxx")
results = client.search("machine learning", limit=5)
for doc in results:
    print(f"{doc.title}: {doc.score}")

client = Client(api_key="sk-xxx")
results = client.search(
    "machine learning",
    filters={"year": 2024, "category": "research"}
)

pip install my-package
# or
npm install my-package
# or
go get github.com/user/project

### API Documentation Patterns

#### OpenAPI / Swagger Specification

```yaml
# openapi.yaml
openapi: 3.0.0
info:
  title: Order Service API
  description: |
    API for managing orders in the e-commerce platform.
    
    ## Authentication
    All requests require a Bearer token in the Authorization header.
    
    ## Rate Limiting
    1000 requests per minute per API key.
  version: 1.0.0
  contact:
    name: API Support
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /orders:
    get:
      summary: List orders
      description: |
        Returns a paginated list of orders for the authenticated user.
        
        Results are ordered by creation date (newest first).
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, confirmed, shipped, delivered, cancelled]
          description: Filter by order status
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Maximum number of orders to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Pagination offset
      responses:
        '200':
          description: A list of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Unauthorized — invalid or missing API key

components:
  schemas:
    Order:
      type: object
      required: [id, user_id, total, status, created_at]
      properties:
        id:
          type: string
          format: uuid
          description: Unique order identifier
          example: "ord_3f8a1c2b"
        user_id:
          type: integer
          description: ID of the user who placed the order
          example: 42
        total:
          type: number
          format: float
          description: Order total in USD
          example: 29.99
        status:
          type: string
          enum: [pending, confirmed, shipped, delivered, cancelled]
          description: Current order status
        items:
          type: array
          description: Items in the order
          items:
            $ref: '#/components/schemas/OrderItem'
        created_at:
          type: string
          format: date-time
          example: "2024-03-15T10:30:00Z"
    
    Pagination:
      type: object
      properties:
        total:
          type: integer
          example: 142
        limit:
          type: integer
          example: 20
        offset:
          type: integer
          example: 0

# Generate a Python client
openapi-generator generate -i openapi.yaml -g python -o client-python

# Generate TypeScript types
openapi-generator generate -i openapi.yaml -g typescript-axios -o client-ts

# Generate interactive docs (redoc)
npx redoc-cli bundle openapi.yaml -o docs/api.html

# Swagger UI (docker)
docker run -p 80:8080 -e SWAGGER_JSON=/openapi.yaml -v $(pwd):/tmp swaggerapi/swagger-ui

/**
 * Processes a payment for an order.
 *
 * This function handles the full payment lifecycle:
 * 1. Validates the payment method
 * 2. Charges the customer via the payment gateway
 * 3. Records the transaction
 * 4. Updates the order status
 *
 * @param orderId - The UUID of the order to process payment for
 * @param paymentMethod - The payment method to use
 * @param options - Optional configuration for retries and idempotency
 * @param options.idempotencyKey - Prevents duplicate charges
 * @param options.maxRetries - Maximum retry attempts on failure (default: 3)
 *
 * @returns The completed transaction details
 *
 * @throws {OrderNotFoundError} If the order doesn't exist
 * @throws {PaymentDeclinedError} If the payment is declined
 * @throws {PaymentGatewayTimeoutError} If the gateway doesn't respond
 *
 * @example
 * ```typescript
 * const transaction = await processPayment(
 *   "ord_3f8a1c2b",
 *   "card_1Abc2Def3",
 *   { idempotencyKey: "idem_001" }
 * );
 * console.log(transaction.status); // "completed"
 * ```
 */
export async function processPayment(
  orderId: string,
  paymentMethod: string,
  options?: PaymentOptions
): Promise<Transaction> {
  // Implementation
}

# TypeScript Documentation Generator
npx typedoc --out docs/api src/

# Python Docstrings
pdoc src/my_package -o docs/api

# Go Doc Comments
godoc -http :6060

# Rust Documentation
cargo doc --open

# .github/workflows/docs.yml
name: Documentation
on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'openapi.yaml'
      - 'docs/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      # Generate API docs from OpenAPI
      - name: Generate API docs
        run: |
          npx @redocly/openapi-cli bundle openapi.yaml -o docs/api/openapi.json
          npx redoc-cli build docs/api/openapi.json -o docs/api/index.html
      
      # Generate code docs
      - name: Generate TypeScript docs
        run: |
          npx typedoc --out docs/api/ts src/
      
      # Generate Python docs
      - name: Generate Python docs
        run: |
          pip install pdoc
          pdoc src/my_package -o docs/api/python
      
      # Build static docs site
      - name: Build docs site
        run: |
          npm run docs:build
      
      # Deploy to GitHub Pages
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_site

# Validate markdown formatting
npx markdownlint-cli2 'docs/**/*.md' '#node_modules'

# Check for broken links
npx hyperlink docs/

# Check for common writing issues
# (passive voice, readability, jargon)
npx write-good docs/**/*.md

# Check OpenAPI spec validity
npx @redocly/cli lint openapi.yaml

# Automatic formatting
npx prettier --write 'docs/**/*.md'

<!-- Dynamic badges that show current status -->
![CI](https://img.shields.io/github/actions/workflow/status/user/project/ci.yml?branch=main)
![Coverage](https://img.shields.io/codecov/c/github/user/project)
![Docs](https://img.shields.io/github/actions/workflow/status/user/project/docs.yml?label=docs)
![Version](https://img.shields.io/npm/v/package-name)
![License](https://img.shields.io/github/license/user/project)
![Downloads](https://img.shields.io/npm/dm/package-name)

# Tutorial: Building Your First Chatbot

> **Goal**: Build a working chatbot in 15 minutes
> **Prerequisites**: Node.js 18+, an API key
> **Difficulty**: Beginner

## Step 1: Set up your project
```bash
mkdir my-chatbot && cd my-chatbot
npm init -y
npm install my-framework

const { Chatbot } = require('my-framework');
const bot = new Chatbot({ apiKey: process.env.API_KEY });

bot.on('message', async (msg) => {
  const reply = await bot.generate(msg.text);
  msg.reply(reply);
});

bot.start();

API_KEY=sk-xxx node index.js
# Send "Hello" to your bot on Telegram

#### How-To Guides (Task-Oriented)

```markdown
# How to Deploy to Production

## Prerequisites
- AWS CLI configured with admin credentials
- Docker installed
- Access to the production ECR repository

## Steps

### 1. Build the Docker image
```bash
docker build -t my-service:latest .

docker tag my-service:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/my-service:latest
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/my-service:latest

aws ecs update-service \
  --cluster production \
  --service my-service \
  --force-new-deployment

aws ecs describe-services \
  --cluster production \
  --services my-service \
  --query 'services[0].deployments[0].rolloutState'

#### Explanation (Understanding-Oriented)

```markdown
# Architecture Overview

## Why Event-Driven Architecture?

We chose event-driven architecture for the Order Service because:

1. **Decoupling**: Order processing, inventory, and shipping can evolve independently
2. **Scalability**: Each service scales based on its own load
3. **Resilience**: If shipping is down, orders are still accepted and processed later

## How Events Flow

```text
Order Service ──► Order Placed Event ──► Inventory Service
                    │
                    ├──► Payment Service
                    │
                    └──► Notification Service

#### Reference (Information-Oriented)

```markdown
# Configuration Reference

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
| `REDIS_URL` | Yes | — | Redis connection string |
| `LOG_LEVEL` | No | `info` | Log level: debug, info, warn, error |
| `PORT` | No | `3000` | HTTP server port |
| `RATE_LIMIT` | No | `100` | Requests per minute per IP |
| `FEATURE_FLAGS` | No | `{}` | JSON object of feature flags |

# .github/release-drafter.yml
name-template: 'v$RESOLVED_VERSION'
tag-template: 'v$RESOLVED_VERSION'
categories:
  - title: '🚀 Features'
    labels:
      - 'feature'
      - 'enhancement'
  - title: '🐛 Bug Fixes'
    labels:
      - 'fix'
      - 'bugfix'
      - 'bug'
  - title: '🧰 Maintenance'
    labels:
      - 'chore'
      - 'refactoring'
      - 'dependencies'
change-template: '- $TITLE (@$AUTHOR)'
version-resolver:
  major:
    labels:
      - 'major'
      - 'breaking'
  minor:
    labels:
      - 'minor'
      - 'feature'
  patch:
    labels:
      - 'patch'
      - 'fix'
      - 'chore'
template: |
  ## What's Changed

  $CHANGES

# Generate changelog from conventional commits
# https://github.com/conventional-changelog

npx conventional-changelog -p angular -i CHANGELOG.md -s

# With standard-version or release-please
npx release-please --release-as minor --token $GITHUB_TOKEN

# Documentation Style Guide

## Voice and Tone
- **Active voice**: "The API returns a list of orders" (not "A list of orders is returned")
- **Second person**: "You can configure the timeout by..." (not "One can configure...")
- **Present tense**: "This function handles payment" (not "This function will handle payment")

## Formatting
- **Code**: Use fenced code blocks with language tags
- **Bold**: For UI elements and button labels
- **Inline code**: For file names, commands, variable names
- **Links**: Use descriptive link text (not "click here")

## Structure
- Start with the most common use case
- One idea per paragraph
- Use lists for sequences and alternatives
- Include a troubleshooting section for common issues

## Examples
- Every API endpoint needs at least one example
- Examples should be copy-paste runnable
- Show both success and error responses
- Use realistic data (not "foo" and "bar")

## README Checklist

- [ ] Project name and one-line description at the top
- [ ] Badges showing build status, coverage, license
- [ ] Quick start that works in under 30 seconds
- [ ] Complete usage example (copy-paste-runnable)
- [ ] API reference with parameters, return types, and errors
- [ ] Installation instructions for all supported platforms
- [ ] Configuration reference (env vars, flags)
- [ ] Link to full documentation
- [ ] Contribution guidelines
- [ ] License information
- [ ] At least one screenshot or diagram (for UI projects)
- [ ] FAQ or troubleshooting section