documentation-writing

What this skill does

# Technical Documentation Writing

This skill activates when writing or improving technical documentation, including README files, API documentation, user guides, and inline code documentation.

## When to Use This Skill

Activate when:
- Writing README files
- Creating API documentation
- Writing user guides or tutorials
- Documenting code with comments or docstrings
- Creating architecture or design documents
- Writing changelogs or release notes

## README Files

### Essential README Structure

Every README should include:

```markdown
# Project Name

Brief one-liner description of the project.

## Overview

2-3 paragraphs explaining what the project does, why it exists, and who it's for.

## Features

- Key feature 1
- Key feature 2
- Key feature 3

## Installation

### Prerequisites

- Requirement 1 (with version)
- Requirement 2 (with version)

### Install Steps

```bash
# Clone repository
git clone https://github.com/user/project.git
cd project

# Install dependencies
npm install  # or pip install -r requirements.txt, mix deps.get, etc.

# Configure
cp .env.example .env
# Edit .env with your settings

# Run
npm start
```

## Quick Start

```bash
# Minimal example to get started
npm start
```

## Usage

### Basic Example

```language
// Clear, runnable example
const example = new Project()
example.doSomething()
```

### Advanced Usage

More complex examples with explanations.

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | string | - | API key for authentication |
| `timeout` | number | 5000 | Request timeout in ms |

## API Reference

Link to detailed API documentation or include core APIs here.

## Development

### Setup Development Environment

```bash
# Development-specific setup
npm install --dev
npm run setup
```

### Running Tests

```bash
npm test
npm run test:coverage
```

### Building

```bash
npm run build
```

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Credits
- Inspirations
- Related projects

## Support

- Documentation: https://docs.example.com
- Issues: https://github.com/user/project/issues
- Discussions: https://github.com/user/project/discussions
```

### README Best Practices

- **Start with a clear one-liner**: Immediately tell readers what the project does
- **Include badges**: Build status, coverage, version, license
- **Show, don't tell**: Use code examples liberally
- **Keep it scannable**: Use headers, lists, and code blocks
- **Make examples runnable**: Readers should be able to copy-paste and run
- **Include visual aids**: Screenshots, diagrams, GIFs when appropriate
- **Update regularly**: Keep documentation in sync with code
- **Think about newcomers**: Write for someone seeing the project for the first time

## API Documentation

### Documenting Functions

**Elixir (@doc):**
```elixir
@doc """
Calculates the sum of two numbers.

## Parameters

- `a` - The first number (integer or float)
- `b` - The second number (integer or float)

## Returns

The sum of `a` and `b`.

## Examples

    iex> Math.add(2, 3)
    5

    iex> Math.add(2.5, 3.7)
    6.2

"""
@spec add(number(), number()) :: number()
def add(a, b) do
  a + b
end
```

**JavaScript (JSDoc):**
```javascript
/**
 * Calculates the sum of two numbers.
 *
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 *
 * @example
 * add(2, 3)
 * // => 5
 */
function add(a, b) {
  return a + b
}
```

**Python (docstring):**
```python
def add(a: float, b: float) -> float:
    """
    Calculate the sum of two numbers.

    Args:
        a: The first number
        b: The second number

    Returns:
        The sum of a and b

    Examples:
        >>> add(2, 3)
        5
        >>> add(2.5, 3.7)
        6.2

    Raises:
        TypeError: If arguments are not numbers
    """
    return a + b
```

**Rust (doc comments):**
```rust
/// Calculates the sum of two numbers.
///
/// # Arguments
///
/// * `a` - The first number
/// * `b` - The second number
///
/// # Returns
///
/// The sum of `a` and `b`
///
/// # Examples
///
/// ```
/// use mylib::add;
///
/// assert_eq!(add(2, 3), 5);
/// assert_eq!(add(2.5, 3.7), 6.2);
/// ```
pub fn add(a: f64, b: f64) -> f64 {
    a + b
}
```

### Module/Class Documentation

Document the purpose, usage, and public API:

```elixir
defmodule MyApp.UserManager do
  @moduledoc """
  Manages user accounts and authentication.

  The UserManager provides functions for creating, updating, and authenticating
  users. It handles password hashing, session management, and user validation.

  ## Usage

      # Create a new user
      {:ok, user} = UserManager.create_user(%{
        email: "[email protected]",
        password: "secure_password"
      })

      # Authenticate
      {:ok, user} = UserManager.authenticate("[email protected]", "secure_password")

      # Update user
      {:ok, updated} = UserManager.update_user(user, %{name: "Alice Smith"})

  ## Configuration

  Configure in `config/config.exs`:

      config :my_app, MyApp.UserManager,
        password_min_length: 8,
        session_timeout: 3600

  """
end
```

### API Endpoint Documentation

Document RESTful APIs clearly:

```markdown
## Endpoints

### Create User

Creates a new user account.

**Endpoint:** `POST /api/users`

**Authentication:** Not required

**Request Body:**

```json
{
  "email": "[email protected]",
  "password": "secure_password",
  "name": "Alice Smith"
}
```

**Response (201 Created):**

```json
{
  "id": "123",
  "email": "[email protected]",
  "name": "Alice Smith",
  "created_at": "2024-01-15T10:30:00Z"
}
```

**Error Responses:**

- `400 Bad Request` - Invalid input
  ```json
  {
    "error": "validation_error",
    "details": {
      "email": ["must be a valid email address"],
      "password": ["must be at least 8 characters"]
    }
  }
  ```

- `409 Conflict` - Email already exists
  ```json
  {
    "error": "email_taken",
    "message": "An account with this email already exists"
  }
  ```

**Example:**

```bash
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure_password",
    "name": "Alice Smith"
  }'
```
```

## User Guides and Tutorials

### Tutorial Structure

```markdown
# Tutorial: Building Your First [Feature]

## What You'll Build

Brief description of the end result.

## Prerequisites

- Knowledge requirement 1
- Installed tool 1
- Account/access requirement

## Step 1: [First Major Step]

Explanation of what we're doing and why.

```language
// Code for this step
```

**What's happening here:**
- Explanation of key line 1
- Explanation of key line 2

## Step 2: [Next Step]

Continue with incremental steps...

## Testing

How to verify it works.

## Next Steps

- Related tutorial 1
- Advanced topic 1
- Further reading
```

### Tutorial Best Practices

- **Show working code first**: Let readers see the goal before diving into details
- **Explain the 'why'**: Don't just show what to do, explain reasoning
- **Incremental steps**: Each step should build on the previous
- **Include checkpoints**: Ways to verify progress
- **Provide complete code**: Include a repository or final code snippet
- **Anticipate problems**: Address common mistakes
- **Link to references**: Point to relevant API docs and resources

## Inline Code Documentation

### When to Write Comments

**DO write comments for:**
- Complex algorithms or business logic
- Non-obvious decisions ("why" not "what")
- Workarounds for bugs or limitations
- Public APIs and exported functions
- Configuration and constants

**DON'T write comments for:**
- Obvious code
- What the code does (prefer clear naming)
- Outdated information
- Co