Update operations/foundations/documentation-styling.md

operations/foundations/documentation-styling.md

@@ -9,11 +9,13 @@ tags:
 This document defines the **authoritative documentation style contract** used throughout the Bunny Lab homelab documentation.
 
 It is intended to be provided to:
+
 - AI assistants
 - Automation tools
 - Contributors
 
 The goal is to ensure all documentation is:
+
 - Technically precise
 - CLI-first
 - Easy to audit
@@ -22,6 +24,7 @@ The goal is to ensure all documentation is:
 ---
 
 ## General Writing Principles
+
 - Write for experienced operators, not beginners
 - Prefer **explicit commands** over descriptive prose
 - Avoid narrative filler
@@ -31,6 +34,7 @@ The goal is to ensure all documentation is:
 
 ## Document Flow and Structure
 Documentation is written with the assumption that the reader:
+
 - Reads **top to bottom**
 - Executes actions within the **current section**
 - Does not require explicit step numbering
@@ -42,11 +46,13 @@ Ordering is implicit and intentional.
 
 ## Core Sections (Recommended)
 Most documents should include, at minimum:
+
 - **Purpose** (why this doc exists)
 - **Assumptions** (platform, privileges, prerequisites)
 - **Procedure** (commands and configuration)
 
 Include these when applicable:
+
 - **Architectural Overview** (diagram or flow)
 - **Validation** (explicit checks with expected output)
 - **Troubleshooting** → **Symptoms** / **Resolution**
@@ -54,6 +60,7 @@ Include these when applicable:
 ---
 
 ## Headings
+
 - `#` — Document title (one per document)
 - `##` — Major logical phases or topics
 - `###` — Subsections only when needed
@@ -68,6 +75,7 @@ Avoid over-fragmentation.
 Admonitions are **intentional and sparse**, not decorative.
 
 Use them to:
+
 - Highlight irreversible actions
 - Call out one-time decisions
 - Enforce safety boundaries
@@ -88,6 +96,7 @@ Do **not** restate obvious information inside admonitions.
 Code blocks are the **primary instructional vehicle**.
 
 ### Rules
+
 - Always fenced
 - Always copy/paste-ready
 - Prefer fewer, larger blocks over many small ones
@@ -105,6 +114,7 @@ Avoid explanatory prose between every command.
 ---
 
 ## Shell Fencing
+
 - Use ```sh for shell commands
 - Use ``` for diagrams or pseudo-structure
 - Do not mix command output with commands unless explicitly labeled
@@ -113,6 +123,7 @@ Avoid explanatory prose between every command.
 
 ## Inline Code
 Use backticks for:
+
 - Dataset names
 - Volume groups
 - Filenames
@@ -125,6 +136,7 @@ Example:
 ---
 
 ## Lists
+
 - Use bullet lists for inventories, criteria, and checks
 - Avoid numbered lists for procedures
 - Ordering is conveyed by section layout, not numbering
@@ -132,6 +144,7 @@ Example:
 ---
 
 ## Diagrams
+
 - ASCII diagrams only
 - Used to describe hierarchy or flow
 - Must reinforce understanding, not decorate
@@ -140,6 +153,7 @@ Example:
 
 ## Validation Sections
 Validation is **mandatory** for any procedure that affects:
+
 - Storage
 - Networking
 - Virtualization
@@ -152,12 +166,14 @@ For lower-risk or informational documents, validation is optional.
 ---
 
 ## Tone and Voice
+
 - Neutral
 - Operational
 - Conservative
 - “Boring is correct”
 
 Avoid:
+
 - Marketing language
 - Storytelling
 - Over-explanation
@@ -165,6 +181,7 @@ Avoid:
 ---
 
 ## Anti-Patterns (Do Not Use)
+
 - Numbered procedural steps
 - GUI-only workflows when CLI exists
 - Excessive screenshots
@@ -176,6 +193,7 @@ Avoid:
 
 ## Summary
 Bunny Lab documentation prioritizes:
+
 - Determinism
 - Safety
 - Reproducibility