markdown-doc-writer（Markdown DOC 写作）

Markdown Documentation Writer

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

Documentation Standards

1. Structure Guidelines

Every document should have:

1. Clear title (H1)
2. Brief description
3. Table of contents (for long docs)
4. Well-organized sections (H2, H3)
5. Code examples
6. Complexity analysis (for algorithms)
7. References/links

Standard Template:

# 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. Algorithm Documentation Format

Use this structure for algorithm problems:

# 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: [example input] Output: [example output] Explanation: [why this is the output]

**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

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

### Python

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

## Alternative Approaches

### Approach 2: [Name]

[Description]

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

### Comparison

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

## Key Takeaways

- [Learning point 1]
- [Learning point 2]

## Related Problems

- [Problem A](https://github.com/yennanliu/cs_basics/blob/HEAD/.claude/skills/markdown-doc-writer/link)
- [Problem B](https://github.com/yennanliu/cs_basics/blob/HEAD/.claude/skills/markdown-doc-writer/link)

3. System Design Documentation Format

Follow the template structure:

# 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

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

## 5. Database Design

### Schema

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

## 6. Detailed Component Design

### Component 1: [Name]

**Responsibility**: [What it does]

**Technology**: [Specific tech choice]

**Scaling**: [How to scale]

## 7. Scalability & Reliability

### Caching Strategy

- [Cache what, where, why]

### Sharding Strategy

- [How to partition data]

### Replication

- [Master-slave setup]

## 8. Trade-offs & Alternatives

| Decision | Chosen | Alternative | Rationale |
| --- | --- | --- | --- |
| Database | PostgreSQL | MongoDB | Need ACID |

## 9. Monitoring & Alerting

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

## 10. Security Considerations

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

## References

- [External resources]

4. Code Formatting

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

Code blocks: Use fenced code blocks with language

public class Example { // Code here }

Supported languages:

• java, python, javascript, sql, bash
• json, yaml, xml, markdown
• c, cpp, scala, go

5. Visual Elements

Tables:

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

Lists:

Unordered:
- Item 1
  - Nested item
- Item 2

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

Emphasis:

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

Links:

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

[ref]: URL "Title"

Images:

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

6. Complexity Analysis Documentation

Standard format:

## 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

Complexity cheat sheet to reference:

| 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. Writing Style Guidelines

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

Pattern template:

# Pattern Name

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

## Template Code

def pattern_template(arr): # Step 1: Setup

# Step 2: Main logic

# Step 3: Return result

## Example Problems

1. [Problem 1](https://github.com/yennanliu/cs_basics/blob/HEAD/.claude/skills/markdown-doc-writer/link) - Easy
2. [Problem 2](https://github.com/yennanliu/cs_basics/blob/HEAD/.claude/skills/markdown-doc-writer/link) - Medium
3. [Problem 3](https://github.com/yennanliu/cs_basics/blob/HEAD/.claude/skills/markdown-doc-writer/link) - Hard

## Key Points

- [Tip 1]
- [Tip 2]

9. Cheat Sheet Format

Keep it scannable:

# Topic Cheat Sheet

## Quick Reference

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

## Common Patterns

### Pattern 1

// Code snippet

**Use when**: [Description]

### Pattern 2

// Code snippet

**Use when**: [Description]

## Gotchas

- ⚠️ [Common mistake 1]
- ⚠️ [Common mistake 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:

1. Algorithm problems: Use detailed format with multiple languages
2. System design: Follow 00_template.md structure
3. Cheat sheets: Keep in doc/ directory
4. Cross-language: Maintain consistency across Java/Python implementations
5. 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/

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