diff --git a/operations/foundations/documentation-styling.md b/operations/foundations/documentation-styling.md index a81d5b2..24f2061 100644 --- a/operations/foundations/documentation-styling.md +++ b/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