markdown-doc-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Documentation Writer

Markdown文档撰写者

When to use this Skill

何时使用该技能

Use this Skill when:

Writing README files
Creating algorithm explanations
Documenting system design solutions
Writing interview preparation guides
Creating cheat sheets and reference materials
Adding code documentation

在以下场景使用该技能：

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

Documentation Standards

文档规范

1. Structure Guidelines

1. 结构指南

Every document should have:

Clear title (H1)
Brief description
Table of contents (for long docs)
Well-organized sections (H2, H3)
Code examples
Complexity analysis (for algorithms)
References/links

Standard Template:

markdown

undefined

每份文档应包含：

清晰的标题（H1）
简短描述
目录（长文档适用）
组织有序的章节（H2、H3）
代码示例
复杂度分析（针对算法文档）
参考资料/链接

标准模板：

markdown

undefined

Title

标题

Brief description of what this document covers.

本文档涵盖内容的简要描述。

Section 1 章节1

Content...

内容...

Section 2 章节2

Content...

内容...

References

参考资料

Link 1

undefined

链接1

undefined

2. Algorithm Documentation Format

2. 算法文档格式

Use this structure for algorithm problems:

markdown

undefined

算法类文档使用以下结构：

markdown

undefined

Problem Number: Problem Title

题目编号: 题目名称

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

难度: 简单/中等/困难主题: 数组, 双指针, 哈希表 涉及公司: Google, Amazon, Meta

Problem Statement

题目描述

[Clear description of the problem]

Example 1:

Input: [example input]
Output: [example output]
Explanation: [why this is the output]

Constraints:

[List constraints]

[清晰的题目描述]

示例1：

输入: [示例输入]
输出: [示例输出]
解释: [输出原因]

约束条件：

[列出约束]

Approach

解题思路

Intuition

核心思路

[Explain the key insight in simple terms]

[用简单语言解释关键思路]

Algorithm

算法步骤

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

[步骤1]
[步骤2]
[步骤3]

Complexity Analysis

复杂度分析

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

时间复杂度: O(n) - [解释原因]
空间复杂度: O(1) - [解释原因]

Solution

解决方案

Java

java

class Solution {
    public ReturnType method(InputType param) {
        // Implementation
    }
}

java

class Solution {
    public ReturnType method(InputType param) {
        // 实现代码
    }
}

Python

python

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

python

class Solution:
    def method(self, param: InputType) -> ReturnType:
        # 实现代码

Alternative Approaches

其他解题思路

Approach 2: [Name]

思路2: [名称]

[Description]

Complexity: O(?) time, O(?) space

[描述]

复杂度: O(?) 时间, O(?) 空间

Comparison

思路对比

Approach	Time	Space	Notes
Approach 1	O(n)	O(1)	Optimal
Approach 2	O(n²)	O(1)	Simpler code

思路	时间	空间	说明
思路1	O(n)	O(1)	最优解
思路2	O(n²)	O(1)	代码更简洁

Key Takeaways

关键要点

[Learning point 1]
[Learning point 2]

[知识点1]
[知识点2]

System Name: Brief Description

系统名称: 简要描述

1. Requirements

1. 需求分析

Functional Requirements

功能需求

Feature 1: [Description]
Feature 2: [Description]

功能1: [描述]
功能2: [描述]

Non-Functional Requirements

非功能需求

Scale: X million DAU, Y QPS
Performance: p99 latency < Z ms
Availability: 99.9% uptime

规模: X百万日活跃用户（DAU）, Y每秒查询率（QPS）
性能: p99延迟 < Z毫秒
可用性: 99.9% 在线率

2. Capacity Estimation

2. 容量估算

Traffic

流量

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

日活跃用户: 1亿
单用户日均请求数: 10次
QPS: 1亿 * 10 / 86400 ≈ 11,574

Storage

存储

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

单用户数据量: 1KB
总存储量: 1亿 * 1KB = 100GB

Bandwidth

带宽

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

平均请求大小: 10KB
带宽: 11,574 QPS * 10KB ≈ 115MB/s

3. API Design

3. API设计

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

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

4. High-Level Architecture

4. 高层架构

[Client] → [Load Balancer] → [App Servers]
                                    ↓
                            [Cache] [DB]

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

5. Database Design

5. 数据库设计

Schema

表结构

sql

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

sql

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

Indexing Strategy

索引策略

Index on
```
username
```
for fast lookup
Index on
```
created_at
```
for sorting

为
```
username
```
创建索引以实现快速查找
为
```
created_at
```
创建索引以支持排序

6. Detailed Component Design

6. 组件详细设计

Component 1: [Name]

组件1: [名称]

Responsibility: [What it does]

Technology: [Specific tech choice]

Scaling: [How to scale]

职责: [功能描述]

技术选型: [具体技术]

扩容方案: [如何扩容]

7. Scalability & Reliability

7. 可扩展性与可靠性

Caching Strategy

缓存策略

[Cache what, where, why]

[缓存内容、位置及原因]

Sharding Strategy

分片策略

[How to partition data]

[数据分区方式]

Replication

复制方案

[Master-slave setup]

[主从架构设置]

8. Trade-offs & Alternatives

8. 权衡与替代方案

Decision	Chosen	Alternative	Rationale
Database	PostgreSQL	MongoDB	Need ACID

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

9. Monitoring & Alerting

9. 监控与告警

Metrics to track: [List]
Alerts: [When to trigger]

需跟踪指标: [列表]
告警触发条件: [何时触发]

10. Security Considerations

10. 安全考量

Authentication: [Method]
Authorization: [Method]
Data encryption: [At rest, in transit]

认证: [方法]
授权: [方法]
数据加密: [静态加密、传输加密]

References

参考资料

[External resources]

undefined

[外部资源]

undefined

4. Code Formatting

4. 代码格式规范

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`

行内代码: 使用

反引号

包裹变量名、命令、短代码

代码块: 使用带语言标识的围栏式代码块

markdown

```java
public class Example {
    // 代码内容
}


**支持的语言:**
- `java`, `python`, `javascript`, `sql`, `bash`
- `json`, `yaml`, `xml`, `markdown`
- `c`, `cpp`, `scala`, `go`

5. Visual Elements

5. 视觉元素

Tables:

markdown

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

Lists:

markdown

Unordered:
- Item 1
  - Nested item
- Item 2

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

Emphasis:

markdown

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

Links:

markdown

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

[ref]: URL "Title"

Images:

markdown

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

表格:

markdown

| 列1 | 列2 | 列3 |
|----------|----------|----------|
| 数据1   | 数据2   | 数据3   |

列表:

markdown

无序列表:
- 项1
  - 嵌套项
- 项2

有序列表:
1. 第一步
2. 第二步
3. 第三步

强调格式:

markdown

*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体***
`代码`
~~删除线~~

链接:

markdown

[链接文本](URL)
[带标题的链接](URL "标题")
[参考式链接][ref]

[ref]: URL "标题"

图片:

markdown

![替代文本](图片链接)
![替代文本](图片链接 "标题")

6. Complexity Analysis Documentation

6. 复杂度分析文档规范

Standard format:

markdown

undefined

标准格式:

markdown

undefined

Complexity Analysis

复杂度分析

Time Complexity: O(n log n)

时间复杂度: O(n log n)

Sorting takes O(n log n)
Single pass takes O(n)
Overall: O(n log n)

排序耗时O(n log n)
单次遍历耗时O(n)
总复杂度: O(n log n)

Space Complexity: O(n)

空间复杂度: O(n)

Hash map stores n elements: O(n)
Result array: O(n)
Overall: O(n)

哈希表存储n个元素: O(n)
结果数组: O(n)
总复杂度: O(n)

Optimization Notes

优化说明

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


**Complexity cheat sheet to reference:**
```markdown
| 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 |

可通过原地修改输入将空间复杂度降至O(1)
权衡: 会破坏原始输入数据


**复杂度速查表参考:**
```markdown
| 符号 | 名称 | 示例 |
|----------|------|---------|
| O(1) | 常数时间 | 数组访问 |
| O(log n) | 对数时间 | 二分查找 |
| O(n) | 线性时间 | 数组遍历 |
| O(n log n) | 线性对数时间 | 归并排序 |
| O(n²) | 平方时间 | 嵌套循环 |
| O(2ⁿ) | 指数时间 | 递归斐波那契 |
| O(n!) | 阶乘时间 | 全排列 |

7. Writing Style Guidelines

7. 写作风格指南

Be Clear:

Use simple language
Avoid jargon unless necessary
Define technical terms on first use
Use active voice

Be Concise:

Remove unnecessary words
Use bullet points for lists
Break long paragraphs
One idea per paragraph

Be Consistent:

Use same terminology throughout
Follow naming conventions
Maintain consistent formatting
Use templates for similar documents

Examples:

❌ Bad:

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

✅ Good:

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

清晰明确:

使用简单语言
避免不必要的行话
首次使用技术术语时给出定义
使用主动语态

简洁凝练:

删除冗余词汇
用列表呈现内容
拆分长段落
每段仅表达一个核心观点

保持一致:

全文使用统一术语
遵循命名规范
保持格式一致
同类文档使用相同模板

示例对比:

❌ 不佳:

这个算法基本上是通过遍历数组，然后检查元素是否是我们要找的。

✅ 优秀:

该算法通过遍历数组查找目标元素。

8. Interview Preparation Docs

8. 面试准备文档

Pattern template:

markdown

undefined

模板格式:

markdown

undefined

Pattern Name

题型名称

When to Use

适用场景

[Characteristic 1]
[Characteristic 2]

[特征1]
[特征2]

Template Code

模板代码

python

def pattern_template(arr):
    # Step 1: Setup

    # Step 2: Main logic

    # Step 3: Return result

python

def pattern_template(arr):
    # 步骤1: 初始化

    # 步骤2: 主逻辑

    # 步骤3: 返回结果

Example Problems

示例题目

Problem 1 - Easy
Problem 2 - Medium
Problem 3 - Hard

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

Key Points

关键要点

[Tip 1]
[Tip 2]

undefined

[技巧1]
[技巧2]

undefined

9. Cheat Sheet Format

9. 速查表格式

Keep it scannable:

markdown

undefined

保持易读性:

markdown

undefined

Topic Cheat Sheet

主题速查表

Quick Reference

快速参考

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

操作	语法	复杂度
访问	arr[i]	O(1)
搜索	arr.indexOf(x)	O(n)

Common Patterns

常见模式

Pattern 1

模式1

code

// Code snippet

Use when: [Description]

code

// 代码片段

适用场景: [描述]

Pattern 2

模式2

code

// Code snippet

Use when: [Description]

code

// 代码片段

适用场景: [描述]

Gotchas

注意事项

⚠️ [Common mistake 1]
⚠️ [Common mistake 2]

undefined

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

undefined

10. Document Maintenance

10. 文档维护

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

版本控制:

使用Git跟踪变更
编写有意义的提交信息
保持文档与代码同步更新

交叉引用:

关联相关文档
引用源代码文件
指向外部资源

验证:

检查所有链接可用
验证代码示例可编译运行
确认复杂度分析准确

Project-Specific Guidelines

项目特定指南

For CS_basics repository:

Algorithm problems: Use detailed format with multiple languages
System design: Follow
```
00_template.md
```
structure
Cheat sheets: Keep in
```
doc/
```
directory
Cross-language: Maintain consistency across Java/Python implementations
Interview prep: Focus on pattern recognition and problem-solving approach

File organization:

doc/
├── algorithm_patterns/
│   ├── two_pointers.md
│   └── sliding_window.md
├── data_structure/
│   └── complexity_chart.md
└── system_design/
    └── case_studies/

针对CS_basics仓库:

算法题目: 使用多语言的详细格式
系统设计: 遵循
```
00_template.md
```
结构
速查表: 存放在
```
doc/
```
目录下
跨语言: 保持Java/Python实现的一致性
面试准备: 重点关注模式识别和解题思路

文件组织结构:

doc/
├── algorithm_patterns/
│   ├── two_pointers.md
│   └── sliding_window.md
├── data_structure/
│   └── complexity_chart.md
└── system_design/
    └── case_studies/

Quality Checklist

质量检查清单

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

Markdown验证:

使用Markdown语法检查工具验证
提交前预览效果
使用一致的换行符

实用符号:

✅ 正确思路标记
❌ 错误思路标记
⚠️ 注意事项标记
💡 技巧标记
📝 重要提示标记

markdown-doc-writer

Original

Translation

Markdown Documentation Writer

Markdown文档撰写者

When to use this Skill

何时使用该技能

Documentation Standards

文档规范

1. Structure Guidelines

1. 结构指南

Title

标题

Table of Contents

目录

Section 1

章节1

Section 2

章节2

References

参考资料

2. Algorithm Documentation Format

2. 算法文档格式

Problem Number: Problem Title

题目编号: 题目名称

Problem Statement

题目描述

Approach

解题思路

Intuition

核心思路

Algorithm

算法步骤

Complexity Analysis

复杂度分析

Solution

解决方案

Java

Java

Python

Python

Alternative Approaches

其他解题思路

Approach 2: [Name]

思路2: [名称]

Comparison

思路对比

Key Takeaways

关键要点

Related Problems

相关题目

3. System Design Documentation Format

3. 系统设计文档格式

System Name: Brief Description

系统名称: 简要描述

1. Requirements

1. 需求分析

Functional Requirements

功能需求

Non-Functional Requirements

非功能需求

2. Capacity Estimation

2. 容量估算

Traffic

流量

Storage

存储

Bandwidth

带宽

3. API Design

3. API设计

4. High-Level Architecture

4. 高层架构

5. Database Design

5. 数据库设计

Schema

表结构

Indexing Strategy

索引策略

6. Detailed Component Design