write-theory-docs

name	write-theory-docs
description	Guidelines for writing theory and concept markdown files in the DevOps Roadmap repository. Triggered when creating or editing `.md` files inside module folders (e.g., `01-linux-and-shell/`, `06-docker/`).

Writing Spec for DevOps Theory Markdown Files

Use this spec whenever you create or edit theory/concept .md files inside any numbered module folder in the Full-DevOps-RoadMap repository.

---

1. Audience & Tone

• Audience: Junior developers or students who have basic programming knowledge but are new to DevOps, infrastructure, and operations.
• Tone: Conversational but technically precise. Write like a senior engineer explaining concepts to a new team member over coffee — friendly, clear, no unnecessary jargon.
• Avoid: Overly academic language, walls of text, and unexplained acronyms. Always expand acronyms on first use (e.g., "DNS (Domain Name System)").

2. File Naming Convention

• Use numbered prefixes to indicate reading order: 01-topic.md, 02-topic.md, etc.
• Use lowercase kebab-case: 03-branching-strategies.md ✅, BranchingStrategies.md ❌.
• Keep filenames short and descriptive (max ~4 words after the number).

3. Document Structure

Every theory file MUST follow this skeleton:

# [Title]

> **TL;DR:** [1-2 sentence summary of the entire page]

## Why This Matters in DevOps
[Brief paragraph connecting this concept to real-world DevOps workflows]

## [Core Concept Sections]
[See Section Content Rules below]

## Key Takeaways
- Bullet list of 3-5 main points the reader should remember

## What's Next?
[1-2 sentences pointing the reader to the next theory file or the lab]

## Further Reading
- [Link 1](url) — short description
- [Link 2](url) — short description

4. Section Content Rules

4.1 Explanations

• Lead with the "why" before the "what" or "how".
• Use short paragraphs (3-5 sentences max).
• Use bold for key terms on first introduction.
• Use analogies and real-world comparisons where possible (e.g., "A container image is like a recipe; a running container is the dish cooked from that recipe.").

4.2 Diagrams (Mermaid)

• Every theory file MUST include at least one Mermaid diagram. Diagrams are not optional.
• Use mermaid fenced code blocks so they render natively on GitHub.
• Preferred diagram types:
  • graph TD / graph LR — for architecture, data flow, and component relationships.
  • sequenceDiagram — for request/response flows, API interactions, and multi-step processes.
  • gitGraph — for Git branching, merging, rebasing visualizations.
  • flowchart — for decision trees and process flows.
  • stateDiagram-v2 — for lifecycle/state transitions (e.g., Pod lifecycle, container states).
• Keep diagrams focused. If a diagram has more than ~15 nodes, split it into multiple diagrams.
• Always add a 1-sentence caption immediately below each diagram explaining what it shows.

4.3 Git Command Visuals (specific to 03-git-and-github/)

• For Git commands (fetch, rebase, merge, cherry-pick, reset, pull, etc.), include before/after Mermaid diagrams showing what the commit graph looks like before and after the command runs.
• Use gitGraph diagrams where possible; fall back to graph LR for more complex visualizations.
• Accompany each diagram pair with the exact command(s) and a plain-English explanation of what happened.

4.4 Tables

• Use tables for comparisons (e.g., "Merge vs Rebase", "VMs vs Containers", "TCP vs UDP").
• Keep tables concise: max ~5 columns, prefer 3.

4.5 Code / Command Examples

• Use fenced code blocks with the correct language identifier (bash, yaml, dockerfile, hcl, etc.).
• Keep examples minimal and focused on the concept being explained.
• Add inline comments (# ...) in code blocks to explain non-obvious lines.
• Do NOT include full lab exercises — those belong in lab.md.

4.6 Callout Boxes

Use GitHub-style alert syntax for important notes:

> [!NOTE]
> Background info or helpful context.

> [!WARNING]
> Common mistakes or dangerous operations.

> [!TIP]
> Best practices and pro tips.

• Use sparingly — max 2-3 per file. Overusing callouts dilutes their impact.

5. Emoji Usage

• Use a single relevant emoji in each ## heading as a visual anchor (matching the existing README style).
• Do NOT use emoji inline within body text.
• Prefer standard, universally-rendered emoji: 🧠 🔀 🌐 📦 🔒 🛡️ 🐳 ☸️ ⚙️ 🔍 📊 🚀 🏗️ 🧩

6. Cross-Referencing

• Link to other theory files in the same module using relative paths: [Branching Strategies](./02-branching-strategies.md).
• Link to other modules using ../ paths: [Docker Architecture](../06-docker/02-docker-architecture.md).
• Link to the module's lab.md when a concept is explored hands-on: "You'll practice this in the lab."

7. Length Guidelines

• Each theory file should be 100–300 lines of Markdown (not counting blank lines).
• If a topic needs more than 300 lines, split it into sub-topics across multiple files.
• Aim for a 10–15 minute read time per file.

8. Quality Checklist (before committing)

• File has a TL;DR at the top
• At least one Mermaid diagram is present and renders correctly
• All acronyms are expanded on first use
• Key terms are bolded on first introduction
• No unexplained jargon
• Code examples have correct language identifiers
• Relative links to other files are correct
• "Key Takeaways" section exists with 3-5 bullets
• "Further Reading" section has at least 2 external links