Documentation That Actually Gets Read

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# Getting Started with Our API

By the end of this tutorial, you'll have made your first API call.

## Prerequisites
- An API key (get one at dashboard.example.com)
- curl or any HTTP client

## Step 1: Test Your Key

Run this command (replace YOUR_KEY):

    curl -H "Authorization: Bearer YOUR_KEY" \
      https://api.example.com/health

You should see: {"status": "ok"}

## Step 2: Make Your First Request
...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# How to Rotate Database Credentials

## When to Use This
Use this guide when credentials are compromised or 
during scheduled rotation.

## Steps

1. Generate new credentials in AWS Secrets Manager
2. Update the application config:
   ```bash
   kubectl set env deployment/api DB_PASSWORD=$NEW_PASS

1

kubectl rollout undo deployment/api

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

def calculate_retry_delay(attempt: int, base_delay: float = 1.0) -> float:
    """
    Calculate exponential backoff delay for retries.
    
    Uses jittered exponential backoff to prevent thundering herd.
    Max delay capped at 60 seconds.
    
    Args:
        attempt: Current attempt number (0-indexed)
        base_delay: Initial delay in seconds
        
    Returns:
        Delay in seconds before next retry
        
    Example:
        >>> calculate_retry_delay(0)  # First retry
        1.0
        >>> calculate_retry_delay(3)  # Fourth retry
        8.0  # (approximately, with jitter)
    """

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# Service Name

One sentence: what this does.

## Quick Start

    docker-compose up
    curl localhost:8080/health

## Documentation

- [Getting Started](docs/getting-started.md)
- [API Reference](docs/api.md)
- [Deployment](docs/deploy.md)

## Development

    make test
    make lint

1
2
3
4
5
6
7
8
9

# deploy.yml
# 
# Deployment workflow for production
# 
# BEFORE RUNNING: Ensure you've completed the pre-deploy 
# checklist: docs/deploy-checklist.md
#
# ROLLBACK: If deployment fails, run:
#   kubectl rollout undo deployment/api

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# CI pipeline
docs_check:
  script:
    # Check for broken links
    - markdown-link-check docs/*.md
    
    # Verify code examples run
    - python docs/test_examples.py
    
    # Check API docs match implementation
    - ./scripts/verify-api-docs.sh

1
2
3
4
5
6

---
title: Database Schema Guide
owner: @alice
last_reviewed: 2026-02-15
review_frequency: quarterly
---

1
2
3
4
5
6
7

# Bad
The user management system allows administrators to 
perform various operations on user accounts...

# Good
To create a user:
    curl -X POST /users -d '{"name": "Alice"}'

1
2
3
4
5
6
7

# Bad
curl -X POST /endpoint -d '{"field": "value"}'

# Good
curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer sk_live_abc123" \
  -d '{"name": "Alice Chen", "email": "alice@company.com"}'

1
2
3
4
5
6
7
8
9

# Bad
The retry logic uses exponential backoff.

# Good
The retry logic uses exponential backoff:
- Attempt 1: wait 1 second
- Attempt 2: wait 2 seconds  
- Attempt 3: wait 4 seconds
- Attempt 4: wait 8 seconds (max)

1
2
3

Deploy using our [standard process](deploy.md). 
If you hit issues, check the [troubleshooting guide](troubleshoot.md)
or ask in #platform-help.