Tutorial Writer

Every tutorial must have these four parts:

1. ORIENTATION (10% of tutorial)
   ├── What will the reader build or learn?
   ├── Why does this matter? (motivation)
   ├── What will they have at the end? (outcome preview)
   └── Estimated time to complete

2. PREREQUISITES (5% of tutorial)
   ├── Required knowledge (with links to learn)
   ├── Required software/tools (with versions)
   ├── Required accounts/API keys
   └── Verification commands to confirm readiness

# ... (condensed) ...
4. WRAP-UP (10% of tutorial)
   ├── Summary of what was built
   ├── Key concepts learned
   ├── Next steps / further reading
   └── Link to complete source code

# Build a Real-Time Chat App with WebSockets

Learn how to build a full-featured chat application with typing indicators,
message history, and user presence. By the end of this tutorial, you will have
a working chat app that multiple users can connect to simultaneously.

**What you will build:**

[Screenshot or GIF of the finished product]

**Time:** 45 minutes
**Difficulty:** Intermediate
**Prerequisites:** Basic JavaScript, familiarity with Node.js
**Source code:** [github.com/org/tutorial-chat-app]([reference URL])
# ... (condensed) ...
- Using the command line for basic operations
- Understanding HTTP request/response basics

If you are new to Node.js, complete the
[Introduction to Node.js]([reference URL]) first.

Progressive Complexity Pattern:

Step 1: Minimal working example (instant gratification)
  └── "Hello World" equivalent that proves the setup works

Step 2: Add the core feature (the reason for the tutorial)
  └── The single most important capability

Step 3: Handle the real world (data, errors, edge cases)
  └── Connect to real data, add error handling

Step 4: Polish (UX, performance, production concerns)
  └── Make it production-worthy

# ... (condensed) ...
  Step 1: Express server that returns "Hello World" on GET /
  Step 2: CRUD endpoints for a single resource (products)
  Step 3: Connect to PostgreSQL, add validation, error handling
  Step 4: Add authentication, pagination, rate limiting
  Step 5: Add WebSocket notifications, caching, testing

## Step 3: Connect to the Database

In this step, you will connect the API to a PostgreSQL database so that
products are persisted between server restarts.

### 3.1 Install the database client

\```shell
install via npm: pg drizzle-orm
install via npm: -D drizzle-kit
\```

### 3.2 Configure the database connection

# ... (condensed) ...
server restarts because it is stored in PostgreSQL.

> **Troubleshooting:** If you get a connection error, make sure your
> PostgreSQL server is running and the `DATABASE_URL` environment variable
> is set. See [Common Mistakes](#common-mistakes) at the end of this tutorial.

Code Sample Best Practices:
├── Every code block must be complete and runnable
│   ├── GOOD: Full file with imports, shown in context
│   ├── BAD: Isolated snippet that cannot run standalone
│   └── If showing a diff, clearly mark added/removed lines
├── Show the file path above each code block
│   └── // src/routes/products.ts
├── Use syntax highlighting (specify language after backticks)
├── Include comments for non-obvious lines
│   ├── Comment the "why", not the "what"
│   ├── GOOD: // Pool reuses connections for better performance
│   ├── BAD: // Create a new pool
│   └── Limit to 1-2 comments per code block
├── Keep blocks under 40 lines (split longer blocks)
├── Use realistic variable names (not foo, bar, baz)
├── Use realistic data ("Wireless Headphones", not "Test Product 1")
├── Show expected output after every command
└── Provide copy button (most doc tools support this)

When modifying existing code, show what changed clearly:

Update `src/routes/products.ts` to add validation:

\```typescript
// src/routes/products.ts
import { z } from 'zod';  // Add this import

// Add this validation schema
const createProductSchema = z.object({
  name: z.string().min(1).max(200),
  price: z.string().regex(/^\d+\.\d{2}$/, 'Price must have 2 decimal places'),
});

# ... (condensed) ...

  const product = await db.insert(products).values(result.data).returning();
  res.status(201).json(product[0]);
});
\```

Include a screenshot when:
├── The reader needs to interact with a GUI (IDE, dashboard, browser)
├── The output is visual (a rendered web page, a chart, a diagram)
├── Configuration involves a multi-step UI workflow
├── The result is hard to describe in text alone
└── You want to show "you should see this" for verification

Do NOT screenshot:
├── Terminal output (use a code block instead)
├── Code (use a code block instead)
├── Simple text that can be described in one sentence
└── Anything that changes frequently (version numbers, UI details)

<!-- Screenshot with alt text and caption -->
![The project dashboard showing three running services with green status indicators](./images/step-3-dashboard.png)

*Figure 3: After deployment, all three services should show green status.*

## Common Mistakes

### "Connection refused" when starting the server

**Symptom:** `Error: connect ECONNREFUSED 127.0.0.1:5432`

**Cause:** PostgreSQL is not running or is listening on a different port.

**Fix:**
\```shell
# Check if PostgreSQL is running
pg_isready

# If not running, start it:
# ... (condensed) ...
netstat -ano | findstr :3000  # Windows

# Kill the process, or use a different port
PORT=3001 npm run dev
\```

For each step in the tutorial, ask:
├── What if a required tool is not installed?
├── What if the user is on a different OS?
├── What if a previous step was done incorrectly?
├── What if versions differ from what we tested?
├── What if there is a network/firewall issue?
├── What if permissions are wrong?
└── What if the user copied the code incorrectly?

For each anticipated error:
├── Describe the exact error message they will see
├── Explain what caused it in plain language
├── Provide a specific fix (commands, not just advice)
└── Link to more detailed help if the fix is complex

## Verify Your Environment

Run this script to check that all prerequisites are installed:

\```shell
#!shell-interpreter
# check-prerequisites.shell-cmd

echo "Checking prerequisites..."

check() {
  local name=$1
  local cmd=$2
  local min_version=$3
# ... (condensed) ...
  [PASS] Git: git version 2.43.0
  [PASS] Docker: Docker version 25.0.2

All prerequisites met. You are ready to start the tutorial.
\```

Exercise Design Rules:
├── Place exercises AFTER the concept is taught (not before)
├── Start with "modify the code you just wrote" (not "start from scratch")
├── Provide the expected result so learners can self-verify
├── Include hints for common stumbling points
├── Offer a complete solution (collapsed/linked) for self-unblocking
├── Graduate difficulty:
│   ├── Exercise 1: Apply what you just learned (repetition)
│   ├── Exercise 2: Combine two concepts (synthesis)
│   └── Exercise 3: Solve a new problem (transfer)
└── Time each exercise (include time estimates)

## Exercises

### Exercise 1: Add a "categories" resource (10 minutes)

Using what you learned about creating CRUD endpoints for products,
add a new resource for product categories.

**Requirements:**
- `GET /categories` - List all categories
- `POST /categories` - Create a category (name is required)
- `GET /categories/:id` - Get a single category
- Categories should have: `id`, `name`, `description` (optional)

**Hints:**
# ... (condensed) ...

**Requirements:**
- Support `?limit=10&cursor=xxx` query parameters
- Return a `next_cursor` field when more results are available
- Default limit is 20, maximum is 100

Tutorial Testing Protocol:
├── Fresh Environment Test
│   ├── Start from a clean machine (or fresh Docker container)
│   ├── Follow every step exactly as written
│   ├── Copy-paste every command (do not type from memory)
│   └── Verify every expected output matches actual output
├── Second Person Test
│   ├── Have someone from target audience follow the tutorial
│   ├── Observe without helping (note where they get stuck)
│   ├── Ask them to think aloud (identify confusing sections)
│   └── Time how long each step takes (update estimates)
├── Platform Test
│   ├── Test on macOS, Linux, and Windows (if applicable)
│   ├── Test on minimum supported versions of tools
# ... (condensed) ...
└── Code Repository
    ├── Final code matches what the tutorial produces
    ├── Repository has a working CI build
    ├── Each major step is a tagged commit or branch
    └── README in the repo links back to the tutorial