readme-craft

# README Craft

**Audience:** Developers creating or improving project documentation.

**Goal:** Generate README files that convert scanners into users within 60 seconds.

## Core Philosophy

A README is a sales pitch, onboarding guide, AND reference manual. Lead with value, prove with examples, document with precision.

## Common Failures

| Failure | Fix |
|---------|-----|
| Installation first | Lead with TL;DR and value prop |
| Describes what it IS | Describe what problem it SOLVES |
| No examples | One example per feature minimum |
| Hidden limitations | Dedicated limitations section |
| Single install method | Three+ pathways (curl, package manager, source) |
| No troubleshooting | Document top 5 common errors |

## Golden Structure

### Tier 1: Hero Section

```markdown
<p align="center">
  <img src="logo.png" width="200" alt="Project Name">
</p>

<p align="center">
  <a href="..."><img src="https://img.shields.io/..." alt="CI"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="Version"></a>
  <a href="..."><img src="https://img.shields.io/..." alt="License"></a>
</p>

<p align="center">
  <b>One-line description of what problem this solves</b>
</p>

```bash
curl -sSL https://example.com/install.sh | bash
```
```

### Tier 2: TL;DR

```markdown
## TL;DR

**Problem:** [Specific pain point users face]

**Solution:** [How this tool solves it]

| Feature | Benefit |
|---------|---------|
| Feature 1 | Quantified benefit |
| Feature 2 | Quantified benefit |
| Feature 3 | Quantified benefit |
```

### Tier 3: Quick Example

```markdown
## Quick Start

# 1. Install
curl -sSL https://example.com/install.sh | bash

# 2. Initialize
mytool init

# 3. Run core workflow
mytool process input.txt --output result.json

# 4. Verify
mytool status
```

**Rule:** 5-10 commands demonstrating the core workflow.

### Tier 4: Reference Sections

- Philosophy/Design decisions
- Alternatives comparison
- Installation (multiple methods)
- Command reference
- Configuration