document

What this skill does

# Documentation Skill

Create clear, useful documentation that helps people understand and use your code.

## Core Principle

**Write for the reader, not for yourself.**

## Name

han-core:document - Generate or update documentation for code, APIs, or systems

## Synopsis

```
/document [arguments]
```

## Types of Documentation

### 1. README Files

**Purpose:** Help users understand what the project does and how to use it

**Audience:** New users, potential contributors

**Key sections:**

- What it does (one paragraph)
- Installation instructions
- Quick start example
- Common use cases
- Link to full documentation
- How to contribute
- License

### 2. API Documentation

**Purpose:** Help developers use your API correctly

**Audience:** Other developers integrating with your code

**Key information:**

- Endpoint/function signature
- Parameters and types
- Return values
- Error cases
- Authentication requirements
- Examples

### 3. Inline Comments

**Purpose:** Explain non-obvious decisions and complex logic

**Audience:** Future developers (including future you)

**When to add:**

- Non-obvious decisions ("why" not "what")
- Complex algorithms
- Workarounds
- Edge cases
- Performance considerations
- Security considerations

### 4. Technical Guides

**Purpose:** Teach how to accomplish specific tasks

**Audience:** Developers working with the system

**Types:**

- How-to guides (step-by-step)
- Architecture overviews (system structure)
- Integration guides (connecting systems)
- Troubleshooting guides (debugging help)

### 5. Architecture Decision Records (ADRs)

**Purpose:** Document important technical decisions and their rationale

**Audience:** Current and future team members

**Key information:**

- Context (what problem exists)
- Decision (what was chosen)
- Alternatives considered
- Consequences (trade-offs)

## Documentation Principles

**Good documentation:**

- **For the reader**: Written for their level and needs
- **Clear**: No jargon unless necessary
- **Concrete**: Examples over abstract descriptions
- **Complete**: Answers the key questions
- **Maintained**: Updated when code changes

**Bad documentation:**

- Explains "what" instead of "why"
- Assumes too much knowledge
- No examples
- Out of date
- Too verbose or too terse

## README Template

```markdown
# Project Name

Brief description (one paragraph) of what this project does and why it exists.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
npm install project-name
```

## Quick Start

```javascript
import { Thing } from 'project-name'

const thing = new Thing()
thing.doSomething()
// Output: ...
```

## Usage

### Basic Usage

[Most common use case with complete example]

### Advanced Usage

[More complex scenarios]

## API Reference

### `functionName(param1, param2)`

Description of what the function does.

**Parameters:**

- `param1` (string, required): Description of parameter
- `param2` (number, optional): Description with default. Default: 42

**Returns:** `string` - Description of return value

**Throws:**

- `Error` - When parameter is invalid

**Example:**

```javascript
const result = functionName('hello', 10)
console.log(result) // "hello repeated 10 times"
```

## Configuration

[How to configure, if applicable]

## Troubleshooting

### Error: "Cannot find module"

**Cause:** Package not installed
**Solution:**

```bash
npm install project-name
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) file for details.

```

## API Documentation Template

### REST API

```markdown
## POST /api/users

Create a new user account.

### Authentication

Requires admin access token in Authorization header.

### Request

**Headers:**
```json
{
  "Content-Type": "application/json",
  "Authorization": "Bearer <admin_token>"
}
```

**Body:**

```json
{
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user"
}
```

**Body Parameters:**

- `email` (string, required): Valid email address. Must be unique.
- `name` (string, required): User's full name. 2-100 characters.
- `role` (string, optional): User role. One of: "user", "admin". Default: "user".

### Response

**Success (201 Created):**

```json
{
  "id": "abc123",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2024-01-01T00:00:00Z"
}
```

**Error Responses:**

**400 Bad Request:**

```json
{
  "error": "Invalid email format",
  "field": "email"
}
```

**401 Unauthorized:**

```json
{
  "error": "Authentication required"
}
```

**403 Forbidden:**

```json
{
  "error": "Admin access required"
}
```

**409 Conflict:**

```json
{
  "error": "Email already exists",
  "field": "email"
}
```

**429 Too Many Requests:**

```json
{
  "error": "Rate limit exceeded. Try again in 60 seconds.",
  "retryAfter": 60
}
```

### Example

**cURL:**

```bash
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abc123..." \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "role": "user"
  }'
```

**JavaScript:**

```javascript
const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer abc123...'
  },
  body: JSON.stringify({
    email: '[email protected]',
    name: 'John Doe',
    role: 'user'
  })
})

const user = await response.json()
console.log(user.id) // "abc123"
```

### Rate Limiting

- 100 requests per minute per API key
- Returns 429 when exceeded
- Check `X-RateLimit-Remaining` header

```

### Function/Method Documentation

```typescript
/**
 * Calculate the total price including tax and shipping.
 *
 * Tax is calculated on the subtotal, not including shipping.
 * Free shipping is applied for orders over $50.
 *
 * @param items - Array of cart items with price and quantity
 * @param shippingAddress - Shipping address for tax calculation
 * @returns Object containing subtotal, tax, shipping, and total
 *
 * @throws {Error} If items array is empty
 * @throws {Error} If any item has invalid price or quantity
 *
 * @example
 * ```typescript
 * const total = calculateTotal([
 *   { price: 10, quantity: 2 },
 *   { price: 15, quantity: 1 }
 * ], { state: 'CA' })
 *
 * console.log(total)
 * // {
 * //   subtotal: 35,
 * //   tax: 2.80,
 * //   shipping: 0,
 * //   total: 37.80
 * // }
 * ```
 */
function calculateTotal(
  items: CartItem[],
  shippingAddress: Address
): OrderTotal {
  // Implementation...
}
```

## Inline Comment Guidelines

### When to Comment

**DO comment:**

- **Why**: Explains reasoning for non-obvious decisions
- **Trade-offs**: Documents deliberate choices
- **Workarounds**: Explains temporary solutions
- **Complex logic**: Clarifies difficult algorithms
- **Edge cases**: Documents special handling
- **Performance**: Explains optimization choices
- **Security**: Notes security considerations

**DON'T comment:**

- **What**: Code is self-explanatory
- **Redundant**: Comment repeats code
- **Obvious**: Anyone can see what it does

### Good vs Bad Comments

```typescript
// BAD: States the obvious
// Loop through users
for (const user of users) {
  // Print user name
  console.log(user.name)
}

// GOOD: Explains why
// Process in creation order to maintain referential integrity
// (newer records may reference older ones)
for (const user of users.sort((a, b) => a.createdAt - b.createdAt)) {
  processUser(user)
}

// BAD: Redundant
// Add 1 to counter
counter = counter + 1

// GOOD: Explains non-obvious decision
// +1 offset because API uses 1-based indexing (not 0-based)
const pageNumber = index + 1

// BAD: Explains what (obvious)
function calculateTotal(price, quantity) {
  // Multiply price by quantity
  return price * quantity
}

// GOOD: Explains why (non-obvious)
function calculateTotal(price, quantity) {
  // Use Number.toFixed(2) to prevent floatin