markdown-doc-writer

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

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:

```markdown

# Title

Brief description of what this document covers.

• [Section 1](#section-1)
• [Section 2](#section-2)

Content...

Content...

• [Link 1](url)

```

2. Algorithm Documentation Format

Use this structure for algorithm problems:

```markdown

# Problem Number: Problem Title

Difficulty: Easy/Medium/Hard

Topics: Array, Two Pointers, Hash Table

Companies: Google, Amazon, Meta

[Clear description of the problem]

Example 1:

```

Input: [example input]

Output: [example output]

Explanation: [why this is the output]

```

Constraints:

• [List constraints]

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]

Java

```java

class Solution {

public ReturnType method(InputType param) {

// Implementation

}

}

```

Python

```python

class Solution:

def method(self, param: InputType) -> ReturnType:

# Implementation

```

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 |

• [Learning point 1]
• [Learning point 2]

• [Problem A](link)
• [Problem B](link)

```

3. System Design Documentation Format

Follow the template structure:

```markdown

# System Name: Brief Description

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

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

```

POST /api/resource

GET /api/resource/{id}

PUT /api/resource/{id}

DELETE /api/resource/{id}

```

```

[Client] → [Load Balancer] → [App Servers]

↓

[Cache] [DB]

```

Schema

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

Component 1: [Name]

Responsibility: [What it does]

Technology: [Specific tech choice]

Scaling: [How to scale]

Caching Strategy

• [Cache what, where, why]

Sharding Strategy

• [How to partition data]

Replication

• [Master-slave setup]

| Decision | Chosen | Alternative | Rationale |

|----------|--------|-------------|-----------|

| Database | PostgreSQL | MongoDB | Need ACID |

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

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

• [External resources]

```

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 |

```

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



```

6. Complexity Analysis Documentation

Standard format:

```markdown

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:

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

```

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:

```markdown

# Pattern Name

• [Characteristic 1]
• [Characteristic 2]

```python

def pattern_template(arr):

# Step 1: Setup

# Step 2: Main logic

# Step 3: Return result

```

1. [Problem 1](link) - Easy
2. [Problem 2](link) - Medium
3. [Problem 3](link) - Hard

• [Tip 1]
• [Tip 2]

```

9. Cheat Sheet Format

Keep it scannable:

```markdown

# Topic Cheat Sheet

| Operation | Syntax | Complexity |

|-----------|--------|------------|

| Access | arr[i] | O(1) |

| Search | arr.indexOf(x) | O(n) |

Pattern 1

```code

// Code snippet

```

Use when: [Description]

Pattern 2

```code

// Code snippet

```

Use when: [Description]

• ⚠️ [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

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/

```

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

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