Cheat Sheet Authoring Skill

Expert knowledge for creating effective, scannable quick reference sheets for the DevOps LMS.

Cheat Sheet Philosophy

Cheat sheets are NOT lesson summaries. They are reference tools designed for:

• Quick lookup during work
• Memory reinforcement after learning
• Print-and-post desk references

File Structure

Location & Naming

• Path: content/{phase}/{topic}/99.cheat-sheet.md
• URL: /phase-1-sdlc/sdlc-models/cheat-sheet
• The 99. prefix ensures it appears last in navigation

Required Frontmatter

---
title: "SDLC Models - Quick Reference"
description: "Key concepts, comparisons, and decision guides for SDLC models"
estimatedMinutes: 5
difficulty: beginner  # Match the topic's average difficulty
learningObjectives:
  - "Quick reference for all SDLC model concepts"
isCheatSheet: true
cheatSheetTopic: "SDLC Models"
---

Required fields:

• isCheatSheet: true - Triggers cheat sheet layout and PDF export
• cheatSheetTopic - Human-readable topic name for PDF metadata

Content Structure Templates

Template 1: Concept Comparison (Best for methodology topics)

## Key Terminology

| Term | Definition |
|------|------------|
| Term 1 | Brief, clear definition |
| Term 2 | Brief, clear definition |

## Quick Comparison

| Aspect | Option A | Option B | Option C |
|--------|----------|----------|----------|
| Best For | Use case | Use case | Use case |
| Team Size | Small | Medium | Large |
| Flexibility | High | Medium | Low |

## Decision Guide

**Choose A when:**
- Condition 1
- Condition 2

**Choose B when:**
- Condition 1
- Condition 2

Template 2: Command Reference (Best for tool topics)

## Essential Commands

| Command | Purpose | Example |
|---------|---------|---------|
| `cmd1` | What it does | `cmd1 --flag value` |
| `cmd2` | What it does | `cmd2 arg1 arg2` |

## Common Patterns

### Pattern Name
```bash
# Step 1: Description
command1

# Step 2: Description
command2 --flag

Troubleshooting

Error	Cause	Solution
Error message	Why it happens	How to fix

### Template 3: Process Reference (Best for workflow topics)

```markdown
## Process Overview

> **Quick Summary:** Brief 1-sentence description of the overall process flow.

## Step-by-Step Quick Reference

### Step 1: Name
- Key action 1
- Key action 2
- **Output**: What this produces

### Step 2: Name
- Key action 1
- Key action 2
- **Output**: What this produces

## Best Practices Checklist

- [ ] Practice 1
- [ ] Practice 2
- [ ] Practice 3

Critical Rules

No Illustrations in Cheat Sheets

IMPORTANT: Cheat sheets must NEVER contain illustrations (MDC components like IllustrationLinearFlow, IllustrationChecklist, IllustrationPyramid, etc.).

Why:

• Cheat sheets are designed for quick scanning and reference
• Illustrations add visual complexity that slows down lookup
• PDF export is optimized for text and tables, not complex SVGs
• Keep cheat sheets pure text/tables for maximum portability

Instead of illustrations, use:

• Tables for comparisons and structured data
• Numbered lists for sequential steps
• Blockquotes for process summaries
• Code blocks for command sequences

Writing Guidelines

Content Density

Do	Don't
Tables for comparisons	Paragraphs of text
Bullet points for lists	Long explanations
Code blocks for commands	Inline code for everything
Short, scannable sections	Wall of text

Table Best Practices

<!-- GOOD: Clear headers, aligned columns -->
| Model | Speed | Quality |
|-------|-------|---------|
| A     | Fast  | Medium  |
| B     | Slow  | High    |

<!-- BAD: Too wide, too much text -->
| Model | Description and full explanation of when to use this model |
|-------|-----------------------------------------------------------|

Code Block Formatting

<!-- GOOD: Short, focused examples -->
```bash
git checkout -b feature/name

# First you need to...
# Then you should...
# After that...

### Visual Hierarchy

1. **H2 (`##`)** for major sections
2. **H3 (`###`)** for subsections
3. **Bold** for key terms in lists
4. **Code** for commands, paths, values
5. Tables for structured data

## PDF Export Considerations

### Page Break Awareness
- Keep related content together
- Tables may break across pages - keep them concise
- Test export with `Download PDF` button

### Print Readability
- Sufficient contrast (dark text on light)
- Readable font sizes (no tiny text)
- Logical reading flow

### Content Length
- Aim for 1-3 printed pages
- More is NOT better for reference sheets
- If too long, split by subtopic

## Quality Checklist

Before finalizing a cheat sheet:

- [ ] `isCheatSheet: true` in frontmatter
- [ ] `cheatSheetTopic` matches topic name
- [ ] **No illustrations** (no MDC illustration components)
- [ ] Scannable in under 30 seconds
- [ ] Tables used for comparisons
- [ ] No paragraphs longer than 2 sentences
- [ ] Code examples are copy-pasteable
- [ ] PDF export tested and readable
- [ ] No quiz section (cheat sheets don't have quizzes)
- [ ] Difficulty set appropriately

## Example: Complete Cheat Sheet

```markdown
---
title: "Git Branching - Quick Reference"
description: "Essential Git branching commands and strategies"
estimatedMinutes: 5
difficulty: beginner
learningObjectives:
  - "Quick reference for Git branching operations"
isCheatSheet: true
cheatSheetTopic: "Git Branching"
---

## Essential Commands

| Command | Purpose |
|---------|---------|
| `git branch` | List branches |
| `git branch name` | Create branch |
| `git checkout name` | Switch branch |
| `git checkout -b name` | Create and switch |
| `git merge name` | Merge branch |
| `git branch -d name` | Delete branch |

## Branching Strategies

| Strategy | Best For | Complexity |
|----------|----------|------------|
| GitHub Flow | Small teams | Low |
| GitFlow | Release cycles | High |
| Trunk-based | CI/CD heavy | Medium |

## Quick Patterns

### Feature Branch
```bash
git checkout -b feature/name
# ... work ...
git push -u origin feature/name

Hotfix

git checkout -b hotfix/name main
# ... fix ...
git checkout main && git merge hotfix/name

Common Mistakes

Mistake	Solution
Working on main	Always branch first
Forgetting to pull	git pull before branch
Long-lived branches	Merge frequently

## Components Reference

### CheatSheetLayout.vue
- Renders cheat sheet content with reference-style layout
- Includes PDF download button
- No "Mark Complete" button
- Uses `#cheat-sheet-content` ID for PDF capture

### CheatSheetPdfButton.vue
- Download button with loading state
- Error display if PDF generation fails

### useCheatSheetPdf.ts
- `downloadCheatSheet(title, slug)` - Generate and download PDF
- `isGenerating` - Loading state
- `error` - Error message if failed