Back to Details

explanation-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Explanation Documentation Skill

解释性文档写作技能

This skill provides patterns for writing effective explanation documents. Explanations are understanding-oriented content for readers who want to know why things work the way they do.
本技能提供了撰写高效解释性文档的模式。解释性内容以帮助读者理解为核心，面向那些想知道事物“为什么”会以当前方式运作的人群。

Purpose & Audience

目的与受众

Target readers:
  • Users who want to understand concepts deeply, not just use them
  • Architects and technical leads evaluating design decisions
  • Team members onboarding to a codebase or system
  • Anyone asking "why?" or "how does this work?"
Explanations are for reading away from the keyboard. Unlike tutorials or how-to guides, readers aren't trying to accomplish a task while reading. They're building mental models.
Explanations are NOT:
  • Tutorials (which teach through hands-on doing)
  • How-To guides (which accomplish specific goals)
  • Reference docs (which look up precise details)
目标读者：
  • 希望深入理解概念，而非仅停留在使用层面的用户
  • 评估设计决策的架构师与技术负责人
  • 刚接触某代码库或系统的团队成员
  • 任何提出“为什么？”或“这是如何运作的？”这类问题的人
解释性文档适合离线阅读。与教程或操作指南不同，读者阅读时无需完成具体任务，而是在构建对事物的心智模型。
解释性文档不是：
  • 教程（通过实操进行教学）
  • 操作指南（完成特定目标）
  • 参考文档（查询精准细节）

Explanation Document Template

解释性文档模板

Use this structure for all explanation documents:
markdown
---
title: "[Concept/System Name] Explained"
description: "Understand how [concept] works and why it was designed this way"
---
所有解释性文档均采用以下结构：
markdown
---
title: "[概念/系统名称] 详解"
description: "了解[概念]的运作方式及设计初衷"
---

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.
简短介绍（2-3句话）：说明本文档的解释内容及其重要性，明确读者读完后能获得的认知。

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>
阐释核心思想。运用类比，将陌生概念与读者已熟知的事物关联起来。
<Note> 解释复杂关系或流程时，可使用图表或可视化辅助工具。 </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]

[备选方案1]

Brief description of an alternative approach. Why wasn't it chosen? Under what circumstances might it be better?
简要描述某一备选方案。为何未被选用？在何种场景下它可能更合适？

[Alternative Approach 2]

[备选方案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

相关概念

undefined
undefined

Writing Principles

写作原则

Focus on Understanding, Not Doing

聚焦理解，而非操作

Explanations answer "why?" and "how does it work?" rather than "how do I?"
Explanation (good)How-To (wrong context)
"The cache uses LRU eviction because memory is limited and recent items are more likely to be accessed again.""To configure the cache, set the 
maxSize
parameter."
"Authentication tokens expire to limit the damage if they're compromised.""Refresh your token by calling the 
/refresh
endpoint."
解释性文档回答“为什么？”和“如何运作？”，而非“我该怎么做？”
解释性内容（正确）操作指南（不适用于此场景）
"缓存采用LRU淘汰机制，因为内存有限，且近期访问的内容再次被访问的概率更高。""要配置缓存，请设置
maxSize
参数。"
"身份验证令牌会过期，以此限制令牌泄露后的危害范围。""调用
/refresh
端点刷新你的令牌。"

Use Analogies and Mental Models

运用类比与心智模型

Connect unfamiliar concepts to things readers already know.
markdown
<!-- Good: Relatable analogy -->
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.

<!-- Avoid: Jumping straight to technical details -->
The message queue implements a FIFO buffer with configurable persistence
and at-least-once delivery semantics.
将陌生概念与读者已了解的事物建立关联。
markdown
<!-- 优秀示例：贴近生活的类比 -->
可以把消息队列想象成邮局。发送者投递消息（信件），邮局会暂存这些消息，直到接收者取走。邮局不关心消息内容——它只负责可靠投递。

<!-- 避免：直接切入技术细节 -->
消息队列实现了一个FIFO缓冲区，具备可配置的持久化能力和至少一次投递语义。

Explain the "Why" Behind Design Decisions

阐释设计决策的“为什么”

Don't just describe what exists - explain why it exists that way.
markdown
<!-- Good: Explains rationale -->
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.

<!-- Avoid: Just states facts -->
The system uses eventual consistency with a 500ms propagation window.
不要只描述现有方案——要解释它为何会是这样。
markdown
<!-- 优秀示例：阐释背后逻辑 -->
我们最终选择最终一致性而非强一致性，因为我们的读密集型工作负载（读写比100:1）从低延迟中获得的收益远大于即时一致性。大多数用户根本注意不到短暂的延迟。

<!-- 避免：仅陈述事实 -->
系统采用最终一致性，传播窗口为500毫秒。

Discuss Trade-offs Honestly

坦诚讨论权衡取舍

Every design choice has costs. Acknowledging them builds trust and helps readers make informed decisions.
markdown
undefined
每个设计选择都有代价。承认这些代价能建立读者的信任，也能帮助他们做出明智的决策。
markdown
undefined

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.
undefined
该架构以写入吞吐量为优化目标，代价是：
  • 读取延迟：查询可能需要访问多个分区
  • 复杂度：开发者必须理解分区键的相关知识
  • 成本：因数据反规范化导致存储成本增加
这种权衡对我们的高容量事件摄入场景是合理的，但可能不适用于读密集型的分析工作负载。
undefined

Structure for Reflection, Not Action

为反思而非行动构建结构

Explanations are read linearly, away from the keyboard. Structure them like essays, not manuals.
  • Use flowing prose more than bullet points
  • Build concepts progressively - each section prepares for the next
  • Allow for depth - it's okay if sections are longer than in how-to guides
  • Include context that would be distracting in task-focused docs
解释性文档适合线性阅读，无需依赖电脑操作。结构应更接近散文，而非手册。
  • 使用流畅的叙述性文字，而非过多项目符号
  • 循序渐进构建概念——每个部分都为下一部分做铺垫
  • 允许内容有深度——篇幅可以比操作指南更长
  • 包含上下文信息——这些信息在任务导向的文档中可能会分散注意力

Connect to the Bigger Picture

关联全局视角

Show how this concept relates to other parts of the system or to broader industry patterns.
markdown
undefined
展示该概念与系统其他部分或行业通用模式的关联。
markdown
undefined

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.
undefined
我们的事件溯源方案是更广泛的CQRS（命令查询职责分离）架构的一部分。理解事件溯源能帮助你明白：
  • 为何我们的读模型是最终一致性的
  • 我们如何“免费”实现审计日志
  • 为何事件重放在我们的测试策略中处于核心地位
如需了解更多CQRS相关内容，请查看架构详解。
undefined

Components for Explanations

解释性文档的组成元素

Diagrams and Visuals

图表与可视化内容

Explanations benefit heavily from visual aids:
markdown
undefined
解释性文档能从可视化辅助工具中大幅获益：
markdown
undefined

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
The load balancer distributes traffic across API gateway instances...
undefined
以下图表展示了请求在系统中的流转路径：
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网关实例...
undefined

Comparison Tables

对比表格

Tables work well for comparing approaches:
markdown
undefined
表格非常适合用于对比不同方案：
markdown
undefined

Comparing Approaches

方案对比

AspectMonolithMicroservices
DeploymentSingle unit, simplerIndependent, more complex
ScalingVerticalHorizontal per service
Team autonomyLowerHigher
Operational overheadLowerHigher
We chose microservices because team autonomy was critical for our 100+ engineer organization...
undefined
维度单体架构微服务架构
部署单一单元，更简单独立部署，更复杂
扩容垂直扩容按服务水平扩容
团队自主性较低较高
运维开销较低较高
我们选择微服务是因为团队自主性对我们拥有100+工程师的组织来说至关重要...
undefined

Callouts for Key Insights

关键见解提示框

markdown
<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>
markdown
<Note>
这是一个常见的混淆点：最终一致性中的“最终”并不意味着“可能”——而是指“不会立即一致，但最终一定会达成一致”。
</Note>

<Warning>
该设计假设网络分区是罕见情况。在网络不可靠的环境中，请考虑采用更强的一致性保证。
</Warning>

Expandable Sections for Depth

可展开的深度内容板块

Use expandables for tangential but valuable details:
markdown
<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>
使用可展开板块放置有价值但非核心的细节内容：
markdown
<Expandable title="历史说明：为何我们从Redis迁移">
我们最初的缓存实现基于Redis。2023年，我们迁移到了自定义方案，原因是...

这些背景信息能解释为何一些旧代码中仍会引用Redis的模式，尽管我们已不再直接使用它。
</Expandable>

Example Explanation Document

解释性文档示例

markdown
---
title: "Understanding Our Authentication System"
description: "Learn how authentication works in our platform and why we designed it this way"
---
markdown
---
title: "身份验证系统详解"
description: "了解我们平台身份验证的运作方式及设计初衷"
---

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.
本文档将解释我们的身份验证系统如何运作，以及背后的设计逻辑。读完本文后，你将理解从登录到API访问的完整流程，以及我们做出这些架构选择的原因。

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.
现代Web应用面临相互矛盾的需求：安全团队希望频繁轮换凭证，而用户期望无需反复登录的流畅体验。传统的基于会话的身份验证需要服务器端存储状态，这给水平扩容带来了挑战。

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.
我们最初使用存储在Redis中的服务器端会话。随着业务扩展到多个区域，会话同步成为了瓶颈。JWT令牌作为无状态身份验证的行业标准兴起后，我们在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.
访问令牌就像会议的单日通行证。它在限定时间内有效，每个入口（API端点）都会检查它。如果通行证被盗，小偷也只能在过期前使用它。
刷新令牌就像你用来领取单日通行证的注册确认单。你不会随身携带它，但可以在通行证过期时用它换取新的通行证。

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.
用户登录时：
  1. 向身份验证服务提供凭证
  2. 凭证验证通过后，用户将同时获得访问令牌（15分钟过期）和刷新令牌（7天过期）
  3. 使用访问令牌发起API请求
  4. 访问令牌过期后，使用刷新令牌获取新的访问令牌
  5. 旧的刷新令牌失效，同时颁发新的刷新令牌
这种轮换机制意味着，即使刷新令牌被盗，在合法用户下次刷新令牌之前，它也只能被使用一次，之后就会失效。

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.
身份验证服务：颁发并验证令牌。对访问令牌是无状态的，维护已撤销刷新令牌的黑名单。
API网关：在每个请求中验证访问令牌。在请求到达后端服务前，拒绝过期或格式错误的令牌。
令牌存储：维护刷新令牌的元数据以支持撤销功能。采用带区域复制的Redis实现。

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.
我们根据自身威胁模型选择了15分钟的过期时间。更短的有效期能限制被盗令牌的滥用窗口，但更频繁的刷新会增加延迟和身份验证服务的负载。我们的分析表明，15分钟的时长能在这些因素与我们的流量模式之间取得平衡。

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.
优先考量：水平可扩展性、通过令牌轮换提升安全性 牺牲的部分：访问令牌无法立即撤销、实现复杂度
即使用户登出，访问令牌在过期前仍保持有效。对大多数场景来说，15分钟的持续访问是可接受的。对于高安全性操作（如修改密码、大额转账），我们会要求重新认证。

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
  • 客户端能安全存储刷新令牌（Web端使用HttpOnly Cookie）
  • 服务器之间的时钟偏差不超过30秒
  • Redis服务可用以验证刷新令牌

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.
性能：身份验证服务每分钟处理约10000次刷新请求。令牌验证是CPU密集型操作（签名验证），因此我们采用水平扩容。
开发者体验：服务无需为身份验证访问数据库——只需验证JWT签名即可。这简化了服务开发流程。
用户体验：大多数用户不会注意到令牌刷新。移动应用会主动刷新令牌，避免在操作过程中出现令牌过期的情况。

Related Concepts

相关概念

undefined
undefined

Checklist for Explanations

解释性文档检查清单

Before publishing, verify:
  • Title indicates this explains a concept (not a how-to)
  • Introduction sets expectations for what reader will understand
  • Background section provides context and history
  • Core concepts explained with analogies or mental models
  • Design decisions include rationale, not just facts
  • Trade-offs discussed honestly
  • Alternatives mentioned and compared
  • Implications for different concerns addressed
  • Related concepts linked
  • Written for reading away from keyboard (no tasks to follow)
  • Progressive structure builds understanding step by step
发布前，请验证以下内容：
  • 标题明确表明这是概念解释文档（而非操作指南）
  • 引言明确了读者读完后能获得的认知
  • 背景部分提供了上下文与历史信息
  • 核心概念通过类比或心智模型进行了解释
  • 设计决策包含背后逻辑，而非仅陈述事实
  • 坦诚讨论了权衡取舍
  • 提及并对比了备选方案
  • 阐述了对不同维度的影响
  • 关联了相关概念
  • 适合离线阅读（无需要执行的任务）
  • 结构循序渐进，逐步构建读者的理解

When to Use Explanation vs Other Doc Types

何时使用解释性文档 vs 其他文档类型

Reader's QuestionDoc TypeFocus
"How do I do X?"How-To GuideSteps to accomplish a goal
"Teach me about X"TutorialLearning through guided doing
"What is the API for X?"ReferencePrecise technical details
"Why does X work this way?"ExplanationUnderstanding and context
"What are the trade-offs of X?"ExplanationDesign rationale
"How does X relate to Y?"ExplanationConceptual connections
读者的问题文档类型核心聚焦
“我该如何做X？”操作指南完成目标的步骤
“教我了解X”教程通过引导式实操学习
“X的API是什么？”参考文档精准的技术细节
“X为什么会这样运作？”解释性文档理解与上下文
“X的权衡取舍有哪些？”解释性文档设计逻辑
“X与Y有何关联？”解释性文档概念关联

Explanation Signals

适合写解释性文档的信号

Write an explanation when users:
  • Ask "why" questions
  • Need to make architectural decisions
  • Are evaluating whether something fits their use case
  • Want to understand design philosophy
  • Need context before diving into implementation
当用户出现以下行为时，应撰写解释性文档：
  • 提出“为什么”类问题
  • 需要做出架构决策
  • 评估某方案是否符合自身场景
  • 希望了解设计理念
  • 需要先掌握上下文，再深入实现细节

Not an Explanation

不适合写解释性文档的场景

If users need to accomplish something while reading, it's not an explanation:
  • "How to configure caching" - How-To Guide
  • "Cache API reference" - Reference Doc
  • "Build a caching layer tutorial" - Tutorial
  • "How caching works and why we use LRU" - Explanation
如果用户需要在阅读时完成任务，那它就不是解释性文档：
  • “如何配置缓存” - 操作指南
  • “缓存API参考” - 参考文档
  • “构建缓存层教程” - 教程
  • “缓存的运作机制及为何使用LRU” - 解释性文档

Related Skills

相关技能

  • docs-style: Core writing conventions and components
  • howto-docs: How-To guide patterns for task-oriented content
  • reference-docs: Reference documentation patterns for lookups
  • tutorial-docs: Tutorial patterns for learning-oriented content
  • docs-style：核心写作规范与组件
  • howto-docs：面向任务型内容的操作指南模式
  • reference-docs：面向查询场景的参考文档模式
  • tutorial-docs：面向学习场景的教程模式