markdown-doc-writer

Markdown 文档撰写指南

何时使用此 Skill

在以下场景中使用此 Skill：

• 编写 README 文件
• 创建算法说明
• 编写系统设计解决方案文档
• 编写面试准备指南
• 创建速查表和参考资料
• 添加代码文档

文档规范

1. 结构指南

doc/cheatsheet/ 和 doc/faq/ 以外的文档通常应包含一个清晰的 H1 标题、一段描述，以及层级不跳级的各个章节。这两个目录树有各自必须遵循的结构（参见下方的项目专属指南）。

标准模板：

# Title

Brief description of what this document covers.

## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)

## Section 1

Content...

## Section 2

Content...

## References
- [Link 1](url)

2. 算法文档格式

算法题请使用以下结构：

# Problem Number: Problem Title

**Difficulty**: Easy/Medium/Hard
**Topics**: Array, Two Pointers, Hash Table
**Companies**: Google, Amazon, Meta

## Problem Statement

[Clear description of the problem]

**Example 1:**

Input: [示例输入] Output: [示例输出] Explanation: [说明为何得到此输出]

**Constraints:**
- [List constraints]

## Approach

### Intuition

[Explain the key insight in simple terms]

### Algorithm

1. [Step 1]
2. [Step 2]
3. [Step 3]

### Complexity Analysis

- **Time Complexity**: O(n) - [Explain why]
- **Space Complexity**: O(1) - [Explain why]

## Solution

### Java
```java
class Solution {
    public ReturnType method(InputType param) {
        // Implementation
    }
}

Python

class Solution:
    def method(self, param: InputType) -> ReturnType:
        # Implementation

其他解法

解法 2：[名称]

[描述]

复杂度：时间 O(?)，空间 O(?)

对比

解法	时间	空间	备注
解法 1	O(n)	O(1)	最优
解法 2	O(n²)	O(1)	代码更简单

关键要点

• [学习要点 1]
• [学习要点 2]

相关题目

• 题目 A
• 题目 B

### 3. System Design Documentation Format

**Follow the template structure:**

```markdown
# System Name: Brief Description

## 1. Requirements

### Functional Requirements
- Feature 1: [Description]
- Feature 2: [Description]

### Non-Functional Requirements
- **Scale**: X million DAU, Y QPS
- **Performance**: p99 latency < Z ms
- **Availability**: 99.9% uptime

## 2. Capacity Estimation

### Traffic
- Daily Active Users: 100M
- Requests per user: 10/day
- QPS: 100M * 10 / 86400 ≈ 11,574

### Storage
- Per user data: 1KB
- Total: 100M * 1KB = 100GB

### Bandwidth
- Average request size: 10KB
- Bandwidth: 11,574 QPS * 10KB ≈ 115MB/s

## 3. API Design

POST /api/resource GET /api/resource/{id} PUT /api/resource/{id} DELETE /api/resource/{id}

## 4. High-Level Architecture

[客户端] → [负载均衡器] → [应用服务器] ↓ [缓存] [数据库]

## 5. Database Design

### Schema

```sql
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

索引策略

• 为 username 创建索引以加快查找
• 为 created_at 创建索引以支持排序

6. 详细组件设计

组件 1：[名称]

职责：[功能]

技术：[具体技术选型]

扩展：[扩展方式]

7. 可扩展性与可靠性

缓存策略

• [缓存什么、在哪里缓存、为何缓存]

分片策略

• [如何划分数据]

复制

• [主从架构]

8. 权衡与替代方案

决策	选择	替代方案	理由
数据库	PostgreSQL	MongoDB	需要 ACID

9. 监控与告警

• 需跟踪的指标：[列表]
• 告警：[触发条件]

10. 安全注意事项

• 身份验证：[方式]
• 授权：[方式]
• 数据加密：[静态数据、传输中数据]

参考资料

• [外部资源]

### 4. Code Formatting

**Inline code**: Use `backticks` for variable names, commands, short code

**Code blocks**: Use fenced code blocks with language

```markdown
```java
public class Example {
    // Code here
}

**Supported languages:**
- `java`, `python`, `javascript`, `sql`, `bash`
- `json`, `yaml`, `xml`, `markdown`
- `c`, `cpp`, `scala`, `go`

### 5. Visual Elements

**Tables:**
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

列表：

Unordered:
- Item 1
  - Nested item
- Item 2

Ordered:
1. First step
2. Second step
3. Third step

强调：

*italic* or _italic_
**bold** or __bold__
***bold italic***
`code`
~~strikethrough~~

链接：

[Link text](URL)
[Link with title](URL "Title")
[Reference link][ref]

[ref]: URL "Title"

图片：

![Alt text](image-url)
![Alt text](image-url "Title")

6. 复杂度分析文档

标准格式：

## Complexity Analysis

### Time Complexity: O(n log n)
- Sorting takes O(n log n)
- Single pass takes O(n)
- Overall: O(n log n)

### Space Complexity: O(n)
- Hash map stores n elements: O(n)
- Result array: O(n)
- Overall: O(n)

### Optimization Notes
- Can reduce space to O(1) by modifying input in-place
- Trade-off: Destroys original input

可供参考的复杂度速查表：

| Notation | Name | Example |
|----------|------|---------|
| O(1) | Constant | Array access |
| O(log n) | Logarithmic | Binary search |
| O(n) | Linear | Array scan |
| O(n log n) | Linearithmic | Merge sort |
| O(n²) | Quadratic | Nested loops |
| O(2ⁿ) | Exponential | Recursive Fibonacci |
| O(n!) | Factorial | Permutations |

7. 写作风格指南

表达清晰：

• 使用简单的语言
• 除非必要，否则避免使用术语
• 首次使用技术术语时进行定义
• 使用主动语态

表达简洁：

• 删除不必要的词语
• 使用项目符号列出清单
• 拆分较长的段落
• 每段只表达一个观点

保持一致：

• 全文使用相同的术语
• 遵循命名约定
• 保持格式一致
• 相似文档使用相同模板

示例：

❌ 不佳：

The algorithm basically works by iterating through the array and
then it checks if the element is what we're looking for.

✅ 良好：

The algorithm iterates through the array to find the target element.

8. 面试准备文档

模式模板：

# Pattern Name

## When to Use
- [Characteristic 1]
- [Characteristic 2]

## Template Code

```python
def pattern_template(arr):
    # Step 1: Setup

    # Step 2: Main logic

    # Step 3: Return result

示例题目

1. 题目 1 - 简单
2. 题目 2 - 中等
3. 题目 3 - 困难

要点

• [提示 1]
• [提示 2]

### 9. Cheat Sheet Format

**Keep it scannable:**
```markdown
# Topic Cheat Sheet

## Quick Reference

| Operation | Syntax | Complexity |
|-----------|--------|------------|
| Access | arr[i] | O(1) |
| Search | arr.indexOf(x) | O(n) |

## Common Patterns

### Pattern 1
```code
// Code snippet

适用场景：[描述]

模式 2

// Code snippet

适用场景：[描述]

注意事项

• ⚠️ [常见错误 1]
• ⚠️ [常见错误 2]

### 10. Document Maintenance

**Version control:**
- Use git to track changes
- Write meaningful commit messages
- Keep documents up to date with code

**Cross-references:**
- Link related documents
- Reference source code files
- Point to external resources

**Validation:**
- Check all links work
- Verify code examples compile
- Test complexity analysis accuracy

## Project-Specific Guidelines

**For CS_basics repository:**

- **Cheatsheets** live in `doc/cheatsheet/` and follow the Cheatsheet Style Guide in
  `CLAUDE.md` (Skeleton A/B, the mandatory Scope line, a `data/cheatsheet_meta.json`
  entry). Use `/lc-cheatsheet` for them; this skill is for everything else.
- **FAQs** live in `doc/faq/` and have a zh overlay; use `/lc-faq-add`.
- **System design** docs follow `system_design/00_template.md`.

## Quality Checklist

Before finalizing documentation:
- [ ] Clear title and description
- [ ] Proper heading hierarchy
- [ ] Code examples tested and working
- [ ] Complexity analysis included
- [ ] Consistent formatting
- [ ] No broken links
- [ ] Spell-checked
- [ ] Follows project conventions
- [ ] Related content linked

## Tools & References

**Markdown validation:**
- Check syntax with markdown linters
- Preview before committing
- Use consistent line breaks

**Useful symbols:**
- ✅ Checkmark for correct approach
- ❌ X for incorrect approach
- ⚠️ Warning for gotchas
- 💡 Bulb for tips
- 📝 Note for important points