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 明确指出，解释是唯一适合表达观点的文档类型：“所有人类活动和知识都蕴含着价值观、判断和观点——甚至可以说是意识形态。”参考文档和操作指南必须保持中立，但拒绝表明立场的解释无法帮助读者形成自己的看法。请明确提出建议并说明理由（“在大多数情况下，我们更倾向于 X 而非 Y，因为……”），指出判断发生变化的条件，并如实说明有争议的观点来自何处。目标是帮助读者获得充分理解，而非营造虚假的中立。

联系更广阔的背景

说明这一概念与系统其他部分或更广泛的行业模式有何关联。解释受其主题限制，而非受具体机制限制，因此可以自由地向外延伸联系——关联相邻系统、历史，甚至代码库之外的理念——只要这些联系能加深理解。

## 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 有什么关系？”	解释文档	概念之间的联系

如需查看完整的 Compass 流程和其他文档类型之间的区别，请参阅 docs-style/references/diataxis-compass.md。

解释类内容的判断信号

当用户：

• 询问“为什么”
• 需要做出架构决策
• 正在评估某项内容是否适用于自己的用例
• 想了解设计理念
• 需要先了解背景信息，再深入实现细节

此时应编写解释类内容。

不属于解释类内容

如果用户需要一边阅读一边完成某项任务，那就不属于解释类内容：

• “如何配置缓存”——操作指南
• “缓存 API 参考”——参考文档
• “构建缓存层教程”——教程
• “缓存如何工作，以及我们为什么使用 LRU”——解释类内容

相关技能

• docs-style：核心写作规范和组件
• Diataxis compass：类型选择、2×2 矩阵和质量模型
• howto-docs：面向任务内容的操作指南模式
• reference-docs：用于查阅的参考文档模式
• tutorial-docs：面向学习内容的教程模式