Documentation-Driven Development: Write Docs First

Code → Test → Document (maybe)

Document → Code → Verify against docs

## Bad (vague)
The `process()` function handles the data.
 
## Good (specific)
The `process()` function validates input data against the schema,
transforms field names from camelCase to snake_case, and returns
a normalized object ready for database insertion.

// First attempt documented
await client.users.create({
  user: {
    userData: {
      userEmail: "jane@example.com",
      userName: "Jane"
    }
  }
});
 
// After writing docs, you realize it's awkward
// Revised API
await client.users.create({
  email: "jane@example.com",
  name: "Jane"
});

# User Authentication Service
 
## Overview
Handles user registration, login, and session management
for the application.
 
## Features
- Email/password registration
- OAuth integration (Google, GitHub)
- JWT-based sessions
- Password reset flow
- Rate limiting on auth endpoints
 
## API Endpoints
- POST /auth/register
- POST /auth/login
- POST /auth/logout
- POST /auth/refresh
- POST /auth/forgot-password
- POST /auth/reset-password
 
## Configuration
Required environment variables:
- JWT_SECRET: Secret key for signing tokens
- OAUTH_GOOGLE_CLIENT_ID: Google OAuth client ID
- RATE_LIMIT_MAX: Max requests per window (default: 100)

## POST /auth/register
 
Creates a new user account.
 
### Request
 
```json
{
  "email": "user@example.com",
  "password": "securePassword123",
  "name": "Jane Doe"
}

{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

 
### Step 3: Write Code Examples
 
Before implementing, write the code developers will use:
 
```javascript
// JavaScript SDK usage
import { AuthClient } from '@yourcompany/auth';
 
const auth = new AuthClient({
  apiKey: process.env.AUTH_API_KEY
});
 
// Register a new user
try {
  const { user, token } = await auth.register({
    email: 'jane@example.com',
    password: 'securePassword123',
    name: 'Jane Doe'
  });
 
  console.log(`Welcome, ${user.name}!`);
} catch (error) {
  if (error.code === 'EMAIL_EXISTS') {
    console.log('Account already exists. Try logging in.');
  }
}

## Edge Cases
 
### Concurrent Registration
If two requests attempt to register the same email simultaneously,
one will succeed and the other will receive EMAIL_EXISTS error.
 
### Email Normalization
Emails are normalized before storage:
- Converted to lowercase
- Whitespace trimmed
- Gmail dots ignored (j.doe@gmail.com = jdoe@gmail.com)
 
### Rate Limiting
Registration is limited to 5 attempts per email per hour.
After exceeding the limit, wait for the cooldown period.

async function register(data: RegisterInput): Promise<AuthResult> {
  // Validate email format (documented requirement)
  if (!isValidEmail(data.email)) {
    throw new AuthError('INVALID_EMAIL', 'Email format is invalid');
  }
 
  // Check password requirements (documented in API spec)
  if (!meetsPasswordRequirements(data.password)) {
    throw new AuthError('WEAK_PASSWORD',
      'Password doesn\'t meet requirements');
  }
 
  // Normalize email (documented edge case)
  const normalizedEmail = normalizeEmail(data.email);
 
  // Check rate limit (documented)
  await checkRateLimit(normalizedEmail, 'registration');
 
  // Check existing user (documented error case)
  const existing = await db.users.findByEmail(normalizedEmail);
  if (existing) {
    throw new AuthError('EMAIL_EXISTS',
      'Account with email already exists');
  }
 
  // Create user and return response matching documented schema
  const user = await db.users.create({
    email: normalizedEmail,
    password: await hash(data.password),
    name: data.name
  });
 
  const token = generateToken(user);
 
  return {
    user: {
      id: user.id,
      email: user.email,
      name: user.name,
      createdAt: user.createdAt
    },
    token
  };
}

# Logger Library
 
## Usage
 
```typescript
import { Logger } from '@internal/logger';
 
const logger = new Logger({
  service: 'user-service',
  level: 'info'
});
 
logger.info('User created', { userId: '123' });
logger.error('Database connection failed', { error });

{
  "timestamp": "2025-01-15T10:30:00Z",
  "level": "info",
  "service": "user-service",
  "message": "User created",
  "context": { "userId": "123" }
}

 
### Configuration Files
 
Document config schema before implementation:
 
```markdown
# Configuration Schema
 
## config.yaml
 
```yaml
server:
  port: 3000           # Port to listen on
  host: "0.0.0.0"      # Host to bind to
 
database:
  url: "postgres://..."  # Connection string
  poolSize: 10           # Connection pool size
  timeout: 30000         # Query timeout (ms)
 
features:
  enableBetaFeatures: false
  maxUploadSize: "10MB"

 
### CLI Tools
 
Document commands before building:
 
```markdown
# CLI Reference
 
## Commands
 
### `init`
Initialize a new project in the current directory.
 
```bash
mytool init [name] [--template=TEMPLATE]

mytool init my-project --template=full

mytool build [--output=DIR] [--minify]

 
## Common Objections (and Rebuttals)
 
### "It slows down development"
 
Short-term, yes. Long-term, no:
 
- **Less rework** from unclear requirements
- **Faster onboarding** for new team members
- **Fewer bugs** from undocumented edge cases
- **Parallel work** enabled by clear contracts
 
### "Requirements change too fast"
 
Documentation is easier to change than code:
 
```diff
## Response
 
- **Success (200 OK)**
+ **Success (201 Created)**
 
  {
-   "id": "123"
+   "user": {
+     "id": "usr_abc123",
+     "email": "user@example.com"
+   }
  }

# CI check: docs must exist for new endpoints
- name: Check documentation coverage
  run: |
    for endpoint in $(grep -r "@route" src/); do
      doc_exists=$(grep -l "$endpoint" docs/)
      if [ -z "$doc_exists" ]; then
        echo "Missing docs for $endpoint"
        exit 1
      fi
    done

# Feature: [Name]
 
## Overview
[One paragraph description]
 
## User Stories
- As a [user], I want to [action] so that [benefit]
 
## API Changes
[New or modified endpoints]
 
## Data Model Changes
[New or modified schemas]
 
## Edge Cases
[Unusual scenarios to handle]
 
## Open Questions
[Things to clarify before implementation]