Writing Great README FilesLesson 2.3

Writing installation instructions that actually work

prerequisite listing, platform-specific instructions, environment variables, dependency management, verification steps, common installation errors

Installation Instructions That Work

Installation instructions fail for one reason: the author skips steps they consider obvious. The reader doesn't share your context. Every assumption is a potential failure point.

List Every Prerequisite

Before any install command, list every dependency with its minimum required version:

## Prerequisites

- Node.js >= 18.0.0
- npm >= 9.0.0
- PostgreSQL >= 14

Verify your versions:
```bash
node --version
npm --version
psql --version
```

Platform-Specific Instructions

If your setup differs between macOS, Linux, and Windows, use tabbed sections or clearly labeled headers. Never write instructions for one OS and assume readers will figure out the rest.

Always Include Verification

End every installation section with a command the reader can run to confirm everything worked:

# Verify installation
npm run health-check

# Expected output:
# ✓ Database connected
# ✓ Server running on port 3000
# ✓ All checks passed

Document Common Failures

List the top 3 errors your users hit during installation and their fixes. Check your issue tracker — the most common problems are already documented there by frustrated users. Convert those into proactive troubleshooting steps.