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

Golden Structure

Tier 1: Hero Section

<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

## 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 options
• Architecture (for complex systems)

Tier 5: Support Sections

• Troubleshooting
• Limitations
• FAQ
• Contributing
• License

Section Templates

Comparison Table

## Why [Tool] Over Alternatives?

| Feature | [Tool] | Alternative A | Alternative B |
|---------|--------|---------------|---------------|
| Speed | 50ms | 200ms | 150ms |
| Memory | 10MB | 50MB | 30MB |
| Feature X | Yes | No | Partial |
| Feature Y | Yes | Yes | No |

**Choose [Tool] when:** [specific use case]
**Choose Alternative A when:** [specific use case]

Installation (Multiple Methods)

## Installation

### Quick Install (Recommended)

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

Package Managers

# macOS
brew install mytool

# Linux
apt install mytool  # Debian/Ubuntu
dnf install mytool  # Fedora

# Windows
winget install mytool

From Source

git clone https://github.com/user/mytool
cd mytool
make install

### Command Reference

```markdown
## Commands

### Global Flags

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Increase output verbosity |
| `-q, --quiet` | Suppress non-error output |
| `--config PATH` | Use custom config file |

### `mytool init`

Initialize a new project.

```bash
mytool init                    # Interactive setup
mytool init --template minimal # Use template
mytool init --force            # Overwrite existing

mytool run

Execute the main workflow.

mytool run input.txt           # Basic usage
mytool run -o output.json      # Custom output
mytool run --dry-run           # Preview changes

### Troubleshooting

```markdown
## Troubleshooting

### Error: "Permission denied"

**Cause:** Installation script lacks execute permissions.

**Fix:**
```bash
chmod +x install.sh
./install.sh

Error: “Command not found”

Cause: Binary not in PATH.

Fix:

export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc for persistence

Error: “Config file not found”

Cause: Missing configuration.

Fix:

mytool init --config

### Limitations

```markdown
## Limitations

**Current constraints:**

| Limitation | Workaround | Planned Fix |
|------------|------------|-------------|
| Max 10MB files | Split large files | v2.0 |
| No Windows GUI | Use WSL | Under review |
| Single-threaded | Use multiple instances | v1.5 |

**Out of scope:**
- Feature X (use [Alternative] instead)
- Feature Y (not planned)

FAQ

## FAQ

<details>
<summary><b>Q: How does this compare to [Alternative]?</b></summary>

[Tool] focuses on [specific strength], while [Alternative] excels at [different use case]. Choose [Tool] when you need [criteria].

</details>

<details>
<summary><b>Q: Can I use this in production?</b></summary>

Yes. [Tool] is used in production by [companies/projects]. See our [stability policy](link).

</details>

Badge Reference

<!-- CI Status -->
![CI](https://github.com/USER/REPO/actions/workflows/ci.yml/badge.svg)

<!-- Version -->
![Version](https://img.shields.io/github/v/release/USER/REPO)

<!-- License -->
![License](https://img.shields.io/badge/license-MIT-blue)

<!-- Downloads -->
![Downloads](https://img.shields.io/github/downloads/USER/REPO/total)

<!-- Package Managers -->
![npm](https://img.shields.io/npm/v/PACKAGE)
![PyPI](https://img.shields.io/pypi/v/PACKAGE)
![Crates.io](https://img.shields.io/crates/v/PACKAGE)
![Gem](https://img.shields.io/gem/v/PACKAGE)

Progressive Disclosure

For long READMEs (1000+ lines):

<details>
<summary><b>Advanced Configuration</b></summary>

[Detailed content here]

</details>

Or externalize:

• docs/CONFIGURATION.md
• docs/ARCHITECTURE.md
• docs/CONTRIBUTING.md

Keep README focused on the 80% use case.

Pre-Publication Checklist

Hero:

• Logo/image present
• Badges current and working
• One-liner describes the problem solved
• Quick install command visible

Content:

• TL;DR within first scroll
• Every feature has an example
• Code blocks are copy-paste ready
• 3+ installation methods documented

Trust:

• Comparison with alternatives (honest)
• Limitations documented
• Top 5 errors in troubleshooting
• All links verified

Polish:

• Consistent terminology
• No stale badges
• Grammar/spelling checked

Anti-Patterns

Reference Examples

Study these for excellent README patterns:

• ripgrep – Benchmark data, comparison matrices
• bat – Feature highlights, visual demos
• starship – Configuration presets, install matrix
• jq – Tutorial progression, manual linking