technical-writing

What this skill does

# Technical Writing

This skill provides comprehensive guidance for creating clear, effective technical documentation that helps users and developers.

## Documentation Structure

### The Four Types of Documentation

**1. Tutorials** (Learning-oriented)
- Goal: Help beginners learn
- Format: Step-by-step lessons
- Example: "Build your first API"

**2. How-to Guides** (Problem-oriented)
- Goal: Solve specific problems
- Format: Numbered steps
- Example: "How to deploy to production"

**3. Reference** (Information-oriented)
- Goal: Provide detailed information
- Format: Systematic descriptions
- Example: API reference, configuration options

**4. Explanation** (Understanding-oriented)
- Goal: Clarify concepts
- Format: Discursive explanations
- Example: Architecture decisions, design patterns

### README Structure

```markdown
# Project Name

Brief description of what the project does (1-2 sentences).

[![Build Status](badge)](link)
[![Coverage](badge)](link)
[![License](badge)](link)

## Features

- Feature 1
- Feature 2
- Feature 3

## Quick Start

```bash
# Installation
npm install project-name

# Usage
npx project-name init
```

## Prerequisites

- Node.js 18+
- PostgreSQL 14+
- Redis 7+

## Installation

### Using npm

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

### Using yarn

```bash
yarn add project-name
```

### From source

```bash
git clone https://github.com/user/project.git
cd project
npm install
npm run build
```

## Configuration

Create a `.env` file:

```env
DATABASE_URL=postgresql://user:password@localhost:5432/db
API_KEY=your_api_key
```

## Usage

### Basic Example

```typescript
import { createClient } from 'project-name';

const client = createClient({
  apiKey: process.env.API_KEY,
});

const result = await client.doSomething();
console.log(result);
```

### Advanced Example

[More complex example with explanations]

## API Reference

See [API.md](./API.md) for complete API documentation.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT © [Author Name]

## Support

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

## Clear Writing Principles

### Use Active Voice

```markdown
❌ Passive: The data is validated by the function.
✅ Active: The function validates the data.

❌ Passive: Errors should be handled by your application.
✅ Active: Your application should handle errors.
```

### Use Simple Language

```markdown
❌ Complex: Utilize the aforementioned methodology to instantiate a novel instance.
✅ Simple: Use this method to create a new instance.

❌ Jargon: Leverage our SDK to synergize with the API ecosystem.
✅ Clear: Use our SDK to connect to the API.
```

### Be Concise

```markdown
❌ Wordy: In order to be able to successfully complete the installation process,
you will need to make sure that you have Node.js version 18 or higher installed
on your system.
✅ Concise: Install Node.js 18 or higher.

❌ Redundant: The function returns back a response.
✅ Concise: The function returns a response.
```

### Use Consistent Terminology

```markdown
❌ Inconsistent:
- Create a user
- Add an account
- Register a member
(All referring to the same action)

✅ Consistent:
- Create a user
- Update a user
- Delete a user
```

## Code Example Best Practices

### Complete, Runnable Examples

```typescript
// ❌ BAD - Incomplete example
user.save();

// ✅ GOOD - Complete example
import { User } from './models';

async function createUser() {
  const user = new User({
    email: '[email protected]',
    name: 'John Doe',
  });

  await user.save();
  console.log('User created:', user.id);
}

createUser();
```

### Show Expected Output

```typescript
// Calculate fibonacci number
function fibonacci(n: number): number {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

console.log(fibonacci(10));
// Output: 55
```

### Highlight Important Parts

```typescript
// Authenticate user with JWT
app.post('/api/auth/login', async (req, res) => {
  const { email, password } = req.body;

  const user = await User.findOne({ email });
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // 👇 Important: Always use bcrypt for password comparison
  const isValid = await bcrypt.compare(password, user.passwordHash);
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  const token = generateToken(user);
  res.json({ token });
});
```

### Provide Context

```typescript
// ❌ BAD - No context
await client.query('SELECT * FROM users');

// ✅ GOOD - With context
// Fetch all active users who logged in within the last 30 days
const activeUsers = await client.query(`
  SELECT id, email, name, last_login
  FROM users
  WHERE status = 'active'
    AND last_login > NOW() - INTERVAL '30 days'
  ORDER BY last_login DESC
`);
```

## Tutorial Structure

### Learning Progression

**1. Introduction** (2-3 sentences)
- What will users learn?
- Why is it useful?

**2. Prerequisites**
- Required knowledge
- Required tools
- Time estimate

**3. Step-by-Step Instructions**
- Number each step
- One concept per step
- Show results after each step

**4. Next Steps**
- Links to related tutorials
- Advanced topics
- Additional resources

### Tutorial Example

```markdown
# Building a REST API with Express

In this tutorial, you'll build a REST API for managing a todo list.
You'll learn how to create routes, handle requests, and connect to a database.

**Time**: 30 minutes
**Level**: Beginner

## Prerequisites

- Node.js 18+ installed
- Basic JavaScript knowledge
- Code editor (VS Code recommended)

## Step 1: Set Up Project

Create a new project directory and initialize npm:

```bash
mkdir todo-api
cd todo-api
npm init -y
```

Install Express:

```bash
npm install express
```

You should see `express` added to your `package.json`.

## Step 2: Create Basic Server

Create `index.js`:

```javascript
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.json({ message: 'Hello, World!' });
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});
```

Run the server:

```bash
node index.js
```

Visit http://localhost:3000 in your browser. You should see:
```json
{ "message": "Hello, World!" }
```

## Step 3: Add Todo Routes

[Continue with more steps...]

## What You Learned

- How to set up an Express server
- How to create REST API routes
- How to connect to a database

## Next Steps

- [Authentication with JWT](./auth-tutorial.md)
- [Deploy to Production](./deploy-guide.md)
- [API Best Practices](./api-best-practices.md)
```

## API Documentation Patterns

### Endpoint Documentation

```markdown
## Create User

Creates a new user account.

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

**Authentication**: Not required

**Request Body**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address (must be valid) |
| password | string | Yes | Password (min 8 characters) |
| name | string | Yes | User's full name (max 100 characters) |

**Example Request**:

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

**Success Response** (201 Created):

```json
{
  "id": "user_abc123",
  "email": "[email protected]",
  "name": "John Doe",
  "createdAt": "2025-10-16T10:30:00Z"
}
```

**Error Responses**:

**400 Bad Request** - Invalid input:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "field": "email"
  }
}
```

**409 Conflict** - Email already exists:
```json
{
  "error": {
    "code": "EMAIL_EXISTS",
    "message": "Email address already registered"
  }
}
```

**Rate Limit**: 5 requests per minute
```

### Function