readme-craft

README の作成

一般的な技術文書の書き方については、technical-writer スキルを参照してください。

よくある失敗

• インストールを最初に掲載する → TL;DR と価値提案から始めます
• それが何かを説明する → どのような問題を解決するかを説明します
• 例がない → 機能ごとに最低 1 つの例を掲載します
• 制限事項が隠れている → 専用の制限事項セクションを設けます
• インストール方法が 1 つだけ → 3 つ以上の方法を掲載します

基本構成

Tier 1: ヒーローセクション

<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

Badge templates: see [references/badge-reference.md](references/badge-reference.md)

### 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 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

ルール： 中核となるワークフローを示すコマンドを 5～10 個掲載します。

Tier 4: リファレンスセクション

• 理念／設計上の判断
• 代替手段との比較
• インストール（複数の方法）
• コマンドリファレンス
• 設定オプション
• アーキテクチャ（複雑なシステムの場合）

Tier 5: サポートセクション

• トラブルシューティング
• 制限事項
• FAQ
• コントリビューション
• ライセンス

セクションのテンプレート

比較表

## Why [Tool] Over Alternatives?

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

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

インストール（複数の方法）

## Installation

### Quick Install (Recommended)

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

パッケージマネージャー

# macOS
brew install mytool

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

# Windows
winget install mytool

ソースからのインストール

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

### Troubleshooting

```markdown
## Troubleshooting

### Error: "Permission denied"

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

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

エラー：「Command not found」

原因： バイナリが PATH にありません。

対処方法：

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

### 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].

</details>

公開前チェックリスト

ヒーロー：

• ロゴ／画像がある
• バッジが最新で動作している
• 1 行で解決する問題を説明している
• クイックインストールコマンドが見える

コンテンツ：

• 最初のスクロール範囲内に TL;DR がある
• すべての機能に例がある
• コードブロックをそのままコピーして実行できる
• 3 つ以上のインストール方法を記載している

信頼性：

• 代替手段との比較がある（正直に記載）
• 制限事項を記載している
• トラブルシューティングに主なエラーを 5 つ掲載している
• すべてのリンクを確認している

アンチパターン

避けること	代わりに行うこと
インストールから始める	価値提案から始める
「このツールは……です」	「このツールは……を解決します」
スクリーンショットだけのデモ	実行可能なコードブロック
例のない主張	機能ごとに例を示す
制限事項を隠す	専用のセクションを設ける

参考例

優れた README の構成を学ぶには、以下を参照してください。

• ripgrep - ベンチマークデータ、比較表
• bat - 機能の紹介、視覚的なデモ
• starship - 設定プリセット、インストール方法の一覧
• jq - チュートリアルの構成、マニュアルへのリンク