technical-writer

テクニカルライター

README 固有のパターン（ヒーロー、TL;DR、クイックスタート）については、readme-craft スキルを参照してください。

コンテンツの種類と執筆ガイドライン

1. 概念の説明

抽象的なアイデアのメンタルモデルを構築します。

# [Concept Name]

## The Problem It Solves

[Concrete scenario where this matters - make the reader FEEL the pain]

## The Core Idea

[One paragraph, one analogy, zero jargon]

## How It Works

[Visual or step-by-step breakdown]

### Step 1: [First thing that happens]
### Step 2: [Next thing]
### Step 3: [Result]

## In Practice

[Code example with annotations]

## Common Misconceptions

- **Myth:** [What people wrongly believe]
- **Reality:** [What's actually true]

## When NOT to Use This

[Explicit boundaries - this builds trust]

書き出しの例：

悪い例：「依存性注入とは、あるデザインパターンであり……」 良い例：「クラスでデータベース接続が必要です。クラス内で作成しますか、それとも外部から渡しますか？この選択によって、コードがテスト可能になるか、悪夢のようになるかが決まります。」

語り口：「ご覧のとおり……」ではなく「これが機能するのは……だからです」と書きます。「明らかに……」ではなく「X だと思うかもしれませんが、実際は Y です」と書きます。「単に」や「ただ」は使いません（難しさを軽視する表現です）。

2. ハウツーガイド

読者が A から B へ最小限の手間で進めるようにします。

# How to [Accomplish Specific Goal]

**Time:** X minutes | **Difficulty:** Beginner/Intermediate/Advanced

## What You'll Build

[Screenshot or description of end result]

## Prerequisites

- [Specific tool/version]
- [Knowledge assumed]

## Steps

### 1. [Action verb] [Object]

[Why this step matters - one sentence]

```code
[Exact command or code]

期待される結果：［表示される内容］

2. ［次の操作］

［同じパターンを続けます］

動作を確認する

［テストコマンドまたは手動での確認］

トラブルシューティング

［エラーメッセージまたは症状］

原因：［発生する理由］ 解決方法：［具体的な解決策］

次のステップ

• ［関連ガイド］
• ［応用トピック］

**Rules:** One action per step. Every step has expected output. Code is copy-paste ready.

### 3. Tutorial (Teaching Through Building)

Teach concepts by building something real.

```markdown
# Build [Something Concrete]

## What You'll Learn

By the end, you'll understand:
- [Concept 1]
- [Concept 2]
- [Concept 3]

## The Project

[Description of what we're building and why it's useful]

## Part 1: [Foundation]

### The Concept

[Brief explanation of the underlying idea]

### Implementing It

[Code with inline explanation]

### What Just Happened

[Reinforce the concept with what they just did]

## Part 2: [Build on Foundation]

[Repeat pattern, each part introducing one new concept]

## Recap

| Concept | Where We Used It |
|---------|------------------|
| [Concept 1] | Part 1 - [specific code] |
| [Concept 2] | Part 2 - [specific code] |

## Challenges

1. **[Easy extension]** - [Hint]
2. **[Medium extension]** - [Hint]
3. **[Hard extension]** - [Hint]

ルール： セクションごとに概念を1つ扱います。実際に動作するものを作ります。間違いと修正方法を示します。進捗を確認するチェックポイントを含めます。

4. 詳細解説／技術記事

熟達した読者向けに、包括的に掘り下げます。

# [Topic]: A Deep Dive

**Reading time:** X minutes | **Audience:** [Intermediate/Advanced] developers

## TL;DR

[3-5 bullet points covering the key insights]

## The Landscape

[Context: what exists, what problem space we're in]

## How [Thing] Actually Works

### Under the Hood

[Technical explanation with diagrams/code]

### The Tradeoffs

| Approach | Pros | Cons | Use When |
|----------|------|------|----------|
| A | | | |
| B | | | |

## Real-World Patterns

### Pattern 1: [Name]

[Code example from production-quality source]

## Common Pitfalls

### Pitfall 1: [Name]

**The mistake:**
```code
[Bad code]

修正方法：

[Good code]

理由：［説明］

さらに読む

• ［リソース 1］ - ［扱う内容］

## Code Examples

**Every code block needs:**
1. Context (what file, what situation)
2. Working code (not pseudocode unless explicitly stated)
3. Key lines highlighted or annotated

```python
# user_service.py - handling authentication

def authenticate(self, credentials):
    user = self.repository.find_by_email(credentials.email)
    if not user:
        return AuthResult.failure("User not found")  # <- Early return pattern

    if not user.verify_password(credentials.password):
        return AuthResult.failure("Invalid password")

    return AuthResult.success(user)  # <- Only success path reaches here

コードの説明： 悪い例：「このコードはユーザーを認証します。」 良い例：「まず失敗条件を確認し（4～8行目）、該当する場合は早期に戻ります。有効な認証情報だけが、10行目の成功処理に進みます。この「ガード節」パターンにより、正常系の処理をインデントせずに記述できます。」

たとえ

なじみのない概念を、なじみのあるものに結び付けます。

概念	たとえ
API のレート制限	1時間に X 人だけ入場させるクラブの用心棒
データベースのインデックス	教科書の索引と、すべてのページを読むことの違い
キャッシュ	よく使うものを机の上に置いておくことと、ファイルキャビネットにしまうこと
負荷分散	食料品店に複数のレジがあること

ルール： 表面的な類似点だけでなく、重要な特性を対応付けます。たとえが当てはまらなくなる点も明示します。ほかの技術概念ではなく、身近な領域を使います。

複雑さへの対処

1. 簡単なケースから始める - 「基本的なシナリオでは、X が起こります」
2. 複雑な要素を1つ加える - 「では、Y の場合はどうでしょうか？」解決策がどう対応するかを示します
3. 全体像を示す - 「本番環境では、さらに Z にも対処します」

よくある失敗

失敗	修正方法
コードをまとめて掲載し、その後に説明する	コードと説明を交互に配置する
「まず、歴史から説明します……」	歴史ではなく、問題から始める
読者が知っていると決めつける（「ご存じのとおり……」）	説明するか、前提知識を説明する資料へのリンクを追加する
例にマジックナンバーや値を使う	現実的で、説明のある値を使う
正常系のみを示す	エラー処理を示す
抽象的な例（Foo、Bar、Widget）	具体的な領域（User、Order、Payment）

品質チェックリスト

構成：

• WHY（動機）から始まっている
• 段階的に複雑さが増している（簡単 -> 複雑）
• 各セクションが単独でも役立つ

コード：

• すべてのコードがテスト済みで、動作する
• コピーしてすぐに使える（隠れた依存関係がない）
• 重要な行に注釈が付いている

明確さ：

• 定義されていない専門用語がない
• 抽象的な概念にたとえがある
• 前提条件が明記されている

信頼性：

• 制限事項を明示している
• この方法を使うべきでない状況を示している

アンチパターン

パターン	修正方法
「単に X を行う」	「単に」を削除する
「明らかなことですが……」	それでも説明する
スクリーンショットだけの手順	テキストやコードを追加する
大量のコードを一度に掲載する	分割して掲載する
「演習として読者に任せる」	解決策を示す
「ドキュメントを参照してください」	重要なポイントを要約する

5. システムドキュメント（アーキテクチャガイド）

複雑なシステムの「何」と「なぜ」を記録する、包括的な技術ドキュメント向けです。

ドキュメント作成プロセス

1. 調査 - コードベースの構造、依存関係、設計パターン、データフローを分析します
2. 構成 - 論理的な階層を作成し、段階的な情報開示を計画して、用語を統一します
3. 執筆 - まずエグゼクティブサマリーを作成し、次に概要アーキテクチャから実装の詳細へと進めます

含めるべき主なセクション

セクション	目的
エグゼクティブサマリー	関係者向けの1ページ概要
アーキテクチャ概要	システムの境界、コンポーネント、相互作用
設計上の決定事項	アーキテクチャ上の選択の根拠
コアコンポーネント	主要な各モジュール／サービスの詳細
データモデル	スキーマ設計とデータフロー
統合ポイント	API、イベント、外部依存関係
デプロイアーキテクチャ	インフラストラクチャと運用上の考慮事項
パフォーマンス特性	ボトルネック、最適化、ベンチマーク
セキュリティモデル	認証、認可、データ保護

システムドキュメント作成のベストプラクティス

• 設計上の決定について、その「理由」を必ず説明します
• 実際のコードベースから具体例を示します
• 読者がシステムを理解するのに役立つメンタルモデルを作成します
• 現在の状態と変遷の履歴の両方を記録します
• トラブルシューティングガイドとよくある落とし穴を含めます
• 対象読者（開発者、アーキテクト、運用担当者）ごとの読み進め方を提示します

参考資料

• 文の構成 - 導入、つなぎ、注意書き、強調の表現