Back to Details

documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Skill

文档编写Skill

Maintain organized, well-structured project documentation. Prioritizes updating existing docs over creating new ones.
维护条理清晰、结构合理的项目文档。优先更新现有文档，而非创建新文档。

When to Use

适用场景

  • Creating or updating any project documentation
  • Before creating a new doc file
  • When documenting technical decisions, API flows, or architecture
  • Writing changelogs, READMEs, or guides
  • 创建或更新任何项目文档
  • 在创建新文档文件之前
  • 记录技术决策、API流程或架构时
  • 编写变更日志（changelog）、README或指南文档

Core Principles

核心原则

1. Update First, Create Never (Unless Necessary)

1. 优先更新，非必要不创建

Before creating any new doc:
  1. Search 
    docs/
    for existing related documentation
  2. Check if content belongs in an existing file
  3. Only create new files for genuinely distinct topics
Existing docs always beat new docs.
创建任何新文档前：
  1. 在
    docs/
    目录下搜索相关的现有文档
  2. 确认内容是否适合添加到现有文件中
  3. 仅针对完全独立的主题创建新文件
现有文档永远优于新文档。

2. Document Metadata Header

2. 文档元数据头部

Every documentation file MUST include a YAML frontmatter header:
markdown
---
title: [Document Title]
created: YYYY-MM-DD
author: [Name or "AI-assisted"]
last_updated: YYYY-MM-DD
updated_by: [Name or "AI-assisted"]
status: [draft | active | deprecated]
---
Rules:
  • created
    and 
    author
    are set once, never changed
  • last_updated
    and 
    updated_by
    change on every edit
  • status
    tracks document lifecycle
每个文档文件必须包含YAML前置元数据头部：
markdown
---
title: [Document Title]
created: YYYY-MM-DD
author: [Name or "AI-assisted"]
last_updated: YYYY-MM-DD
updated_by: [Name or "AI-assisted"]
status: [draft | active | deprecated]
---
规则：
  • created
    和
    author
    一旦设置，不得修改
  • 每次编辑时更新
    last_updated
    和
    updated_by
  • status
    用于跟踪文档生命周期

3. Minimal Document Count

3. 最小化文档数量

✅ Good❌ Bad
One architecture.md with sectionsarch-frontend.md, arch-backend.md, arch-db.md
Flowcharts in technical-flows.mdauth-flow.md, api-flow.md, ai-flow.md
Single CHANGELOG.mdrelease-notes-v1.md, release-notes-v2.md
✅ 推荐做法❌ 错误做法
单个architecture.md包含多个章节arch-frontend.md, arch-backend.md, arch-db.md
流程图统一放在technical-flows.md中auth-flow.md, api-flow.md, ai-flow.md
单个CHANGELOG.mdrelease-notes-v1.md, release-notes-v2.md

4. Standard Doc Structure

4. 标准文档结构

docs/
├── architecture.md        # Technical patterns & decisions
├── technical-flows.md     # Mermaid diagrams & API flows
├── product-requirements.md  # PRD (if applicable)
├── [topic]-guide.md       # Only for major topics
└── competitive-analysis-[name].md  # Market research
Root-level docs (not in docs/):
  • README.md
    — Project overview
  • CHANGELOG.md
    — Version history
  • TASKS.md
    — Sprint/backlog
  • CONTRIBUTING.md
    — Contribution guide (if open source)
docs/
├── architecture.md        # 技术模式与决策
├── technical-flows.md     # Mermaid图表与API流程
├── product-requirements.md  # 产品需求文档（PRD，如有需要）
├── [topic]-guide.md       # 仅用于重大主题
└── competitive-analysis-[name].md  # 市场调研
根目录下的文档（不在docs/内）：
  • README.md
    — 项目概述
  • CHANGELOG.md
    — 版本历史
  • TASKS.md
    — 迭代/待办事项
  • CONTRIBUTING.md
    — 贡献指南（开源项目适用）

Mermaid Diagram Guidelines

Mermaid图表规范

Flowcharts (LR or TD)

流程图（LR或TD方向）

mermaid
flowchart LR
    A[User Action] --> B{Decision}
    B -->|Yes| C[Result A]
    B -->|No| D[Result B]
mermaid
flowchart LR
    A[User Action] --> B{Decision}
    B -->|Yes| C[Result A]
    B -->|No| D[Result B]

Sequence Diagrams

时序图

mermaid
sequenceDiagram
    participant U as User
    participant A as App
    participant S as Server
    
    U->>A: Action
    A->>S: Request
    S-->>A: Response
    A-->>U: Update
mermaid
sequenceDiagram
    participant U as User
    participant A as App
    participant S as Server
    
    U->>A: Action
    A->>S: Request
    S-->>A: Response
    A-->>U: Update

State Diagrams

状态图

mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: fetch
    Loading --> Success: data
    Loading --> Error: error
    Success --> Idle: reset
    Error --> Idle: retry
mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: fetch
    Loading --> Success: data
    Loading --> Error: error
    Success --> Idle: reset
    Error --> Idle: retry

Best Practices

最佳实践

  1. Label everything — Edges and nodes should be self-explanatory
  2. Left-to-right for flows — Easier to read
  3. Top-down for hierarchies — Natural reading order
  4. Group related nodes — Use subgraphs for clarity
  5. Keep it simple — Max 10-15 nodes per diagram
  1. 所有元素添加标签 — 连接线和节点应清晰易懂
  2. 流程图采用从左到右布局 — 更易阅读
  3. 层级结构采用从上到下布局 — 符合自然阅读顺序
  4. 相关节点分组 — 使用子图提升清晰度
  5. 保持简洁 — 每张图最多包含10-15个节点

Updating Documentation Checklist

文档更新检查清单

When updating any doc:
  • Update 
    last_updated
    date in header
  • Update 
    updated_by
    in header
  • Remove outdated information (don't just add)
  • Verify all links still work
  • Check code samples are current
  • Confirm mermaid diagrams render correctly
更新任何文档时：
  • 更新头部的
    last_updated
    日期
  • 更新头部的
    updated_by
    信息
  • 删除过时内容（不要仅添加新内容）
  • 验证所有链接是否可用
  • 检查代码示例是否为当前版本
  • 确认Mermaid图表渲染正常

Document Discovery

文档检索

Before creating a new doc, always run:
bash
undefined
创建新文档前，务必执行以下命令：
bash
undefined

List existing docs

列出所有现有文档

ls -la docs/
ls -la docs/

Search for related content

搜索相关内容

grep -ri "search term" docs/
grep -ri "search term" docs/

Find mermaid diagrams

查找Mermaid图表

grep -r "mermaid" docs/

---
grep -r "mermaid" docs/

---

Templates

模板

New Section in Existing Doc

现有文档新增章节

markdown
---
markdown
---

[Section Title]

[章节标题]

Added: YYYY-MM-DD
[Content...]
undefined
Added: YYYY-MM-DD
[Content...]
undefined

New Document (only when justified)

新文档模板（仅在必要时使用）

markdown
---
title: [Document Title]
created: YYYY-MM-DD
author: [Name or "AI-assisted"]
last_updated: YYYY-MM-DD
updated_by: [Name or "AI-assisted"]
status: draft
---
markdown
---
title: [Document Title]
created: YYYY-MM-DD
author: [Name or "AI-assisted"]
last_updated: YYYY-MM-DD
updated_by: [Name or "AI-assisted"]
status: draft
---

[Title]

[Title]

[One-line description]
[一句话描述]

Overview

概述

[Content...]

---
[Content...]

---

Anti-Patterns

反模式示例

❌ Don't✅ Do Instead
Create auth-flow.mdAdd Auth section to technical-flows.md
Duplicate content across filesReference other docs with links
Leave stale datesUpdate metadata on every edit
Create docs for every minor featureDocument in code comments
Write docs without checking existingAlways search first
❌ 请勿这样做✅ 正确做法
创建auth-flow.md在technical-flows.md中添加认证流程章节
在多个文件中重复内容通过链接引用其他文档
保留过期的日期信息每次编辑时更新元数据
为每个小功能单独创建文档在代码注释中记录
不检查现有文档就创建新文档先搜索现有文档

Changelog Conventions

变更日志规范

Follow Keep a Changelog format:
markdown
undefined
遵循Keep a Changelog格式：
markdown
undefined

[Unreleased]

[Unreleased]

Added

Added

  • New feature description
  • 新功能描述

Changed

Changed

  • Modified behavior
  • 修改的行为

Fixed

Fixed

  • Bug fix description
  • Bug修复描述

Removed

Removed

  • Deprecated feature
  • 已弃用的功能

[1.0.0] - YYYY-MM-DD

[1.0.0] - YYYY-MM-DD

Added

Added

  • Initial release features

**Categories:** Added, Changed, Deprecated, Removed, Fixed, Security

---
  • 初始版本功能

**分类：** Added、Changed、Deprecated、Removed、Fixed、Security

---

Quick Reference

快速参考

ItemValue
Metadata requiredtitle, created, author, last_updated, updated_by, status
Max docs in docs/~5-7 files for typical project
Always updatelast_updated, updated_by on every edit
Mermaid typesflowchart (LR/TD), sequenceDiagram, stateDiagram-v2, erDiagram
Status valuesdraft, active, deprecated
项值
必填元数据title、created、author、last_updated、updated_by、status
docs/目录最大文档数典型项目约5-7个文件
每次编辑必须更新last_updated、updated_by
Mermaid图表类型flowchart（LR/TD）、sequenceDiagram、stateDiagram-v2、erDiagram
状态值draft、active、deprecated

License

许可证

MIT
MIT