Layer 1: README / Landing (30 seconds)
   ↓
Layer 2: Quickstart (5 minutes)
   ↓
Layer 3: Tutorials (30 minutes)
   ↓
Layer 4: Reference (as needed)
   ↓
Layer 5: Deep Dives (when ready)

# Project Name

One-line description of what this does and who it's for.

## Quick Start

[Fastest possible path to "hello world"]

## Installation

[Complete installation for all platforms]

## Usage

[Common patterns with examples]

## Documentation

[Links to full docs]

## Contributing

[How to help]

## License

[Legal stuff]

[Project Name] is a [category] that [primary action] for [target user].

// Context: Where does this code go?
// File: src/api/users.ts

import { createClient } from '@example/sdk'  // Dependencies shown

// Create client with required config
const client = createClient({
  apiKey: process.env.API_KEY,  // Environment variables, not hardcoded
  region: 'us-west-2'
})

// Usage pattern - the actual thing they're learning
const users = await client.users.list({
  limit: 10,
  status: 'active'
})

// What to expect
console.log(users)
// → [{ id: '123', name: 'Alice', ... }, ...]

// Basic usage
const result = await api.query('SELECT * FROM users')

// With options
const result = await api.query('SELECT * FROM users', {
  timeout: 5000,
  cache: true
})

// With error handling
try {
  const result = await api.query('SELECT * FROM users')
} catch (error) {
  if (error instanceof QueryTimeout) {
    // Handle timeout specifically
  }
  throw error
}

# Comment explaining what this does
$ command --flag value
Expected output here

// Bad: Placeholders without explanation
const client = new Client(YOUR_API_KEY)

// Bad: Partial code
// ... some code ...
const result = await fetch()

// Bad: Outdated patterns
var data = null
fetch(url, function(err, res) { ... })

// Bad: Console.log without expected output
console.log(response)

// Good: Environment variable pattern
const client = new Client(process.env.API_KEY)

// Good: Complete context
import { Client } from '@example/sdk'
const client = new Client(process.env.API_KEY)
const result = await client.fetch('/users')

// Good: Modern patterns
const data: User | null = await fetchUser(id)

// Good: Expected output shown
console.log(response)
// → { status: 200, data: { id: '123', name: 'Alice' } }

## Create User

Creates a new user in the system.

### Request

`POST /api/v1/users`

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | Must be `application/json` |

#### Body Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| email | string | Yes | User's email address |
| name | string | Yes | Display name (2-100 chars) |
| role | string | No | One of: `admin`, `user`. Default: `user` |

#### Example Request

```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "name": "Alice Smith",
    "role": "admin"
  }'

{
  "id": "usr_abc123",
  "email": "alice@example.com",
  "name": "Alice Smith",
  "role": "admin",
  "createdAt": "2025-01-15T10:30:00Z"
}

### SDK Documentation Pattern

```typescript
/**
 * Creates a new user in the system.
 *
 * @param options - User creation options
 * @returns The created user object
 * @throws {ValidationError} When email format is invalid
 * @throws {ConflictError} When email already exists
 *
 * @example
 * ```ts
 * const user = await client.users.create({
 *   email: 'alice@example.com',
 *   name: 'Alice Smith'
 * })
 * console.log(user.id) // → 'usr_abc123'
 * ```
 */
async create(options: CreateUserOptions): Promise<User>

> **Version:** This document applies to v2.x. For v1.x docs, see [here](link).
> **Last updated:** 2025-01-15

# Getting Started with [Product]

Get [Product] running in under 5 minutes.

## Prerequisites

Before you begin, ensure you have:
- Node.js 18 or later
- An API key ([get one here](link))

## Step 1: Install

```bash
npm install @example/sdk

API_KEY=your_api_key_here

import { Client } from '@example/sdk'

const client = new Client(process.env.API_KEY)
const result = await client.ping()
console.log(result) // → { status: 'ok' }

node index.js

### How-To Guide

```markdown
# How to [Accomplish Task]

[One sentence describing what this guide helps you do.]

## Prerequisites

- [Requirement 1]
- [Requirement 2]

## Steps

### 1. [First action]

[Explanation if needed]

```code
example

### Migration Guide

```markdown
# Migrating from v1 to v2

## Overview

v2 introduces [major changes]. This guide covers:
- Breaking changes and how to handle them
- New features you can adopt
- Deprecations to address

**Estimated time:** 30 minutes for most projects

## Breaking Changes

### [Change 1]: New authentication method

**Before (v1):**
```typescript
const client = new Client(apiKey)

const client = new Client({ apiKey })

// Example

---

## Quality Checklist

Before publishing any documentation:

### Accuracy
- [ ] All code examples tested and runnable
- [ ] Links verified working
- [ ] Version numbers current
- [ ] Screenshots match current UI

### Completeness
- [ ] Prerequisites listed
- [ ] All required steps included
- [ ] Error cases addressed
- [ ] Next steps provided

### Clarity
- [ ] One idea per paragraph
- [ ] Technical terms defined
- [ ] Consistent terminology throughout
- [ ] Headings are descriptive

### Experience
- [ ] Can complete the task in stated time
- [ ] No assumed knowledge beyond stated prerequisites
- [ ] Works on stated platforms
- [ ] Copy-paste code actually works

---

<skill_compositions>
## Skill Compositions

### technical-writer + dmitrii-writing-style
**Creates:** Documentation with authentic voice

Use when documentation needs personality while maintaining technical accuracy. Apply dmitrii-writing-style's directness and warmth to technical content.

### technical-writer + first-time-user
**Creates:** Validated documentation

Write docs, then test them with first-time-user simulation. Fix friction points. Repeat until smooth.

### technical-writer + ultrathink
**Creates:** Thoughtful documentation architecture

Before writing, ultrathink the information architecture. Who are the users? What are their jobs to be done? What's the right structure?

### technical-writer + serghei-qa
**Creates:** Battle-tested examples

Write the docs, then have Serghei review the code examples for edge cases, error handling, and security issues.
</skill_compositions>

---

## Anti-Patterns

**Wall of Text**
Break it up. Use headers, lists, code blocks, and whitespace.

**Tutorial-Reference Hybrid**
Don't explain concepts in reference docs. Don't list every option in tutorials.

**Placeholder Examples**
`YOUR_API_KEY_HERE` without explaining how to get one is a dead end.

**Screenshot-Only Documentation**
Screenshots break. Always include text alternatives.

**Assuming the Happy Path**
Document what happens when things go wrong.

**Writing for Yourself**
You already know how it works. Write for someone who doesn't.

---

## The Meta-Rule

The best documentation disappears. When someone finishes using your docs, they should feel like the product was so intuitive they barely needed help.

If your docs feel like a maze, your product probably is too. Documentation problems are often product problems in disguise.

---

*Now: what are we documenting?*