explanation-docs

解説ドキュメントのスキル

このスキルでは、効果的な解説ドキュメントを書くためのパターンを紹介します。解説とは、物事がそのように機能する理由を知りたい読者に向けた、理解を重視するコンテンツです。

依存関係： 基本的な執筆原則については、このスキルを docs-style と併用してください。チュートリアル、ハウツー、リファレンスではなく、解説が適切な形式かどうかを確認するには、docs-style/references/diataxis-compass.md を参照してください。

目的と対象読者

対象読者：

• 概念を使うだけでなく、深く理解したいユーザー
• 設計上の判断を評価するアーキテクトやテクニカルリード
• コードベースやシステムのオンボーディングを受けるチームメンバー
• 「なぜ？」「これはどのように機能するのか？」と考えるすべての人

解説は、キーボードから離れて読むためのものです。 チュートリアルやハウツーガイドとは異なり、読者は読みながらタスクを完了しようとしているわけではありません。頭の中に概念モデルを築いています。

解説は、次のものではありません。

• 実際に手を動かして学ぶチュートリアル
• 特定の目的を達成するハウツーガイド
• 正確な詳細を調べるリファレンスドキュメント

解説ドキュメントのテンプレート

すべての解説ドキュメントで、この構成を使用します。

---
title: "[Concept/System Name] Explained"
description: "Understand how [concept] works and why it was designed this way"
---

# Understanding [Concept]

Brief intro (2-3 sentences): What this document explains and why it matters. Set expectations for what the reader will understand after reading.

## Overview

High-level summary of the concept. What is it? What problem does it solve? This should be understandable without deep technical knowledge.

## Background and Context

### The Problem

What situation or challenge led to this design? What were users or developers struggling with?

### Historical Context

How did we get here? What came before? This helps readers understand why alternatives were rejected or why certain constraints exist.

## How It Works

### Core Concepts

Explain the fundamental ideas. Use analogies to connect to concepts readers already understand.

<Note>
Use diagrams or visual aids when explaining complex relationships or flows.
</Note>

### The Mechanism

Walk through how the system actually operates. This is conceptual, not procedural - explain the "what happens" rather than "what to do."

### Key Components

Break down the major parts and how they interact. For each component:
- What role does it play?
- How does it relate to other components?

## Design Decisions and Trade-offs

### Why This Approach?

Explain the reasoning behind key design choices. What goals drove these decisions?

### Trade-offs Made

Every design involves trade-offs. Be explicit about:
- What was prioritized
- What was sacrificed
- Under what conditions this design excels or struggles

### Constraints and Assumptions

What constraints shaped the design? What assumptions does it rely on?

## Alternatives Considered

### [Alternative Approach 1]

Brief description of an alternative approach. Why wasn't it chosen? Under what circumstances might it be better?

### [Alternative Approach 2]

Another alternative. Comparing alternatives helps readers understand the design space.

## Implications and Consequences

What does this design mean for:
- Performance?
- Scalability?
- Developer experience?
- Future extensibility?

## Related Concepts

- [Related Concept 1](/concepts/related-1) - How it connects to this topic
- [Related Concept 2](/concepts/related-2) - Another related area
- [Deeper Technical Reference](/reference/detail) - For implementation specifics

執筆原則

行動ではなく理解に焦点を当てる

解説では「どうすればよいか」ではなく、「なぜか」「どのように機能するのか」に答えます。

解説（適切な例）	ハウツー（不適切な文脈）
「メモリには限りがあり、最近使われた項目は再びアクセスされる可能性が高いため、キャッシュは LRU 方式で項目を削除します。」	「キャッシュを設定するには、maxSize パラメーターを指定します。」
「認証トークンは、漏えいした場合の被害を抑えるために有効期限が設けられています。」	「/refresh エンドポイントを呼び出してトークンを更新します。」

たとえ話や概念モデルを使う

不慣れな概念を、読者がすでに知っている事柄と結び付けます。

Think of the message queue like a post office. Messages (letters) are dropped off
by senders and held until recipients pick them up. The post office doesn't care
about the content - it just ensures reliable delivery.


The message queue implements a FIFO buffer with configurable persistence
and at-least-once delivery semantics.

設計上の判断の「理由」を説明する

存在するものを説明するだけでなく、なぜそのような形で存在するのかを説明します。

We chose eventual consistency over strong consistency because our read-heavy
workload (100:1 read-to-write ratio) benefits more from low latency than from
immediate consistency. Most users never notice the brief delay.


The system uses eventual consistency with a 500ms propagation window.

トレードオフを率直に論じる

どの設計上の選択にもコストがあります。それを認めることで信頼が生まれ、読者が十分な情報に基づいて判断できるようになります。

## Trade-offs

This architecture optimizes for **write throughput** at the cost of:

- **Read latency**: Queries may need to hit multiple partitions
- **Complexity**: Developers must understand partition keys
- **Cost**: More storage due to denormalization

This trade-off makes sense for our use case (high-volume event ingestion)
but may not suit read-heavy analytics workloads.

行動ではなく、考察に適した構成にする

解説はキーボードから離れて、順を追って読まれます。マニュアルではなく、エッセイのように構成します。

• 箇条書きよりも、流れるような文章を使います
• 概念を段階的に積み上げます。各セクションが次のセクションの準備となるようにします
• 深く掘り下げます。ハウツーガイドよりセクションが長くても問題ありません
• タスク重視のドキュメントでは邪魔になるような背景情報も含めます

解説の範囲を守る

Diátaxis は、解説を「最も軽視されやすく、最も誤解されやすい」種類としています。ほかの種類に属する内容を取り込みやすいためです。セットアップ手順が段落として紛れ込んだり、パラメーター表が加わったりすると、いつの間にか解説ではなくなっています。

境界を守りましょう。読者が実行すべき手順を書いているなら、それはハウツーに属します。参照するための正確なシグネチャやオプションを列挙しているなら、それはリファレンスに属します。内容をそのまま埋め込むのではなく、該当するドキュメントにリンクしてください。「なぜ」と「どのように機能するのか」の範囲を守ることこそが、キーボードから離れて読む価値のある解説にします。

順調に進んでいるかを見分ける目安があります。「X の理由は、歴史的に……だからです」「X は Y より優れています。なぜなら……だからです」「Z を好むチームもあります。これは……の場合にはうまく機能しますが……」といった、話を展開する書き出しで自然に読めるのが解説です。あるセクションをそのように表現できないなら、解説ではない可能性があります。

意見や判断を示す

Diataxis では、意見を述べてよいのは「解説」だけだと明確にされています。「あらゆる人間の活動や知識には、価値観、判断、意見が織り込まれています。あえて言えば、イデオロギーさえもです」。リファレンスとハウツーは中立を保つ必要がありますが、立場を示さない解説では、読者が自分で考えをまとめる助けになりません。推奨事項を示して理由を述べ（「ほとんどの場合、Y より X を選びます。なぜなら……」）、判断が変わる条件を明示し、議論のある主張には正直に出典を示しましょう。目指すのは、見せかけの中立性ではなく、十分な情報に基づく理解です。

より大きな全体像と結び付ける

この概念がシステムの他の部分や、業界全体のより広い傾向とどう関係するかを示しましょう。解説の範囲は、仕組みではなく トピック によって決まります。そのため、理解を深めるのに役立つのであれば、関連するシステム、歴史、さらには目の前のコードベースを超えた考え方にも自由に触れられます。

## Related Concepts

Our event sourcing approach is part of our broader CQRS (Command Query
Responsibility Segregation) architecture. Understanding event sourcing
helps explain:

- Why our read models are eventually consistent
- How we achieve audit logging "for free"
- Why replaying events is central to our testing strategy

For more on CQRS, see [Understanding Our Architecture](/concepts/cqrs-architecture).

解説に使うコンポーネント

図とビジュアル

解説では、視覚的な補助が大いに役立ちます。

## System Architecture

The following diagram shows how requests flow through the system:

```mermaid
graph LR
    A[Client] --> B[Load Balancer]
    B --> C[API Gateway]
    C --> D[Service A]
    C --> E[Service B]
    D --> F[(Database)]
    E --> F

ロードバランサーは、API ゲートウェイのインスタンス間にトラフィックを分散します……

### Comparison Tables

Tables work well for comparing approaches:

```markdown
## Comparing Approaches

| Aspect | Monolith | Microservices |
|--------|----------|---------------|
| Deployment | Single unit, simpler | Independent, more complex |
| Scaling | Vertical | Horizontal per service |
| Team autonomy | Lower | Higher |
| Operational overhead | Lower | Higher |

We chose microservices because team autonomy was critical for our
100+ engineer organization...

重要なポイントを強調する

<Note>
This is a common source of confusion: the "eventual" in eventual consistency
doesn't mean "maybe" - it means "not immediately, but guaranteed eventually."
</Note>

<Warning>
This design assumes network partitions are rare. In environments with
unreliable networks, consider stronger consistency guarantees.
</Warning>

詳細情報を折りたたみ可能にする

関連性は薄くても役立つ詳細には、折りたたみ可能なセクションを使います。

<Expandable title="Historical note: Why we migrated from Redis">
Our original implementation used Redis for caching. In 2023, we migrated
to a custom solution because...

This context explains why some older code references Redis patterns
even though we no longer use it directly.
</Expandable>

解説ドキュメントの例

---
title: "Understanding Our Authentication System"
description: "Learn how authentication works in our platform and why we designed it this way"
---

# Understanding Our Authentication System

This document explains how our authentication system works and the reasoning
behind its design. After reading, you'll understand the flow from login to
API access and why we made the architectural choices we did.

## Overview

Our authentication system uses short-lived access tokens with long-lived refresh
tokens. This pattern, sometimes called "token rotation," balances security with
user experience by limiting exposure while avoiding frequent re-authentication.

## Background and Context

### The Problem

Modern web applications face competing demands: security teams want frequent
credential rotation, while users expect seamless experiences without constant
logins. Traditional session-based authentication requires server-side state,
complicating horizontal scaling.

### Historical Context

We originally used server-side sessions stored in Redis. As we scaled to
multiple regions, session synchronization became a bottleneck. JWT tokens
emerged as an industry standard for stateless authentication, and we adopted
them in 2022.

## How It Works

### Core Concepts

**Access tokens** are like day passes at a conference. They grant entry for a
limited time and are checked at each door (API endpoint). If someone steals
your day pass, they can only use it until it expires.

**Refresh tokens** are like the registration confirmation you used to get your
day pass. You don't carry it around, but you can use it to get a new day pass
when yours expires.

### The Authentication Flow

When a user logs in:

1. They provide credentials to the authentication service
2. If valid, they receive both an access token (15-minute expiry) and
   a refresh token (7-day expiry)
3. The access token is used for API requests
4. When the access token expires, the refresh token obtains a new one
5. The old refresh token is invalidated, and a new one is issued

This rotation means that even if a refresh token is compromised, it can only
be used once before the legitimate user's next refresh invalidates it.

### Key Components

**Authentication Service**: Issues and validates tokens. Stateless for access
tokens, maintains a denylist for revoked refresh tokens.

**API Gateway**: Validates access tokens on every request. Rejects expired or
malformed tokens before requests reach backend services.

**Token Store**: Maintains refresh token metadata for revocation. Uses Redis
with regional replication.

## Design Decisions and Trade-offs

### Why Short-Lived Access Tokens?

We chose 15-minute expiry based on our threat model. Shorter expiry limits the
window for stolen token abuse, but more frequent refreshes increase latency
and auth service load. Our analysis showed 15 minutes balances these concerns
for our traffic patterns.

### Trade-offs Made

**Prioritized**: Horizontal scalability, security through token rotation
**Sacrificed**: Immediate revocation of access tokens, simplicity

Access tokens remain valid until expiry even after logout. For most use cases,
15 minutes of continued access is acceptable. For high-security operations
(password changes, large transfers), we require re-authentication.

### Constraints and Assumptions

- Clients can securely store refresh tokens (HttpOnly cookies for web)
- Clock skew between servers is under 30 seconds
- Redis is available for refresh token validation

## Alternatives Considered

### Server-Side Sessions

Traditional sessions would allow immediate revocation but require sticky
sessions or distributed session storage. We rejected this due to scaling
complexity and regional latency concerns.

### Longer Access Token Expiry

Longer-lived tokens reduce auth service load but increase risk from token
theft. Given our security requirements, we prioritized shorter windows.

## Implications and Consequences

**Performance**: Auth service handles ~10K refresh requests per minute. Token
validation is CPU-bound (signature verification), so we scale horizontally.

**Developer Experience**: Services never need database access for auth - they
just validate JWT signatures. This simplifies service development.

**User Experience**: Most users never notice token refresh. Mobile apps
refresh proactively to avoid mid-action expiry.

## Related Concepts

- [API Gateway Architecture](/concepts/api-gateway) - How the gateway validates tokens
- [Token Security Best Practices](/concepts/token-security) - Secure storage guidance
- [Authentication API Reference](/reference/auth-api) - Endpoint documentation

解説のチェックリスト

公開前に、次の点を確認してください。

• タイトルから、ハウツーではなく概念を解説する文書だと分かる
• 導入部で、読者が何を理解できるようになるかを示している
• 背景セクションで、文脈と歴史を説明している
• 中核となる概念を、たとえやメンタルモデルを使って説明している
• 設計上の決定について、事実だけでなく根拠も示している
• トレードオフを率直に論じている
• 代替案を挙げ、比較している
• さまざまな関心事項への影響に触れている
• 関連する概念へのリンクがある
• キーボードから離れて読むことを想定して書かれている（手順を実行する必要がない）
• 段階的な構成によって、一歩ずつ理解を深められる

「完了」にする前のゲート（順番に実施）

順番に実行してください。先に進まないでください。各ステップには、客観的な合格条件があります。

1. 分類 — 解説と他のドキュメント種別の使い分けを使って、この文書が解説（チュートリアル、ハウツー、リファレンスではなく）かどうか判断します。合格条件： 読者の主な疑問がこの表の「解説」の行に当てはまり、さらに導入部で読者が得られる理解を述べていること（短い一文で十分です）。
2. 骨組み — ドラフトを解説ドキュメントのテンプレートに沿わせます。合格条件： ドラフトに、概要、仕組み、および設計上の決定とトレードオフか検討した代替案の少なくとも一方について、プレースホルダーではない実質的な内容が含まれていること。
3. 根拠 — 合格条件： 主要な設計またはアーキテクチャに関する主張すべてに、選択した理由か、受け入れるトレードオフのいずれかが含まれていること（存在するものの説明だけでは不十分です）。
4. チェックリスト — 解説のチェックリストを完了します。合格条件： 各項目を満たすか、理由を添えて文章中で明示的に適用除外としていること。

解説と他のドキュメント種別の使い分け

読者の疑問	ドキュメント種別	主な内容
「X はどうすればできますか？」	ハウツーガイド	目標を達成するための手順
「X について教えてください」	チュートリアル	ガイドに沿って実践しながら学ぶ
「X の API 仕様は何ですか？」	リファレンス	正確な技術的詳細
「X はなぜこのように動作するのですか？」	解説	理解と文脈
「X のトレードオフは何ですか？」	解説	設計の根拠
「X は Y とどう関係していますか？」	解説	概念上のつながり

コンパスの手順全体と、他の種類との違いについては、docs-style/references/diataxis-compass.mdを参照してください。

解説の目印

次のような場合は、解説を書きます。

• 「なぜ」と尋ねている
• アーキテクチャ上の判断が必要
• 自分のユースケースに適しているか評価している
• 設計思想を理解したい
• 実装に進む前に背景を知りたい

解説ではないもの

読みながら何かを実行する必要がある場合、それは解説ではありません。

• 「キャッシュを設定する方法」— ハウツーガイド
• 「キャッシュ API リファレンス」— リファレンスドキュメント
• 「キャッシュレイヤーを構築するチュートリアル」— チュートリアル
• 「キャッシュの仕組みと LRU を採用する理由」— 解説

関連スキル

• docs-style：執筆規則とコンポーネントの基本
• Diataxis compass：種類の選択、2×2 マップ、品質モデル
• howto-docs：タスク指向のコンテンツ向けハウツーガイドのパターン
• reference-docs：参照用ドキュメントのパターン
• tutorial-docs：学習指向のコンテンツ向けチュートリアルのパターン