Additional Doc Restructure

operations/foundations/documentation-styling.md

@@ -0,0 +1,177 @@
+## Purpose
+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
+- Easy to reproduce
+
+---
+
+## General Writing Principles
+- Write for experienced operators, not beginners
+- Prefer **explicit commands** over descriptive prose
+- Avoid narrative filler
+- Assume the reader understands the underlying technologies
+
+---
+
+## 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
+
+Sections define **context and scope**.  
+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**
+
+---
+
+## Headings
+- `#` — Document title (one per document)
+- `##` — Major logical phases or topics
+- `###` — Subsections only when needed
+
+Headings replace the need for numbered steps.
+
+Avoid over-fragmentation.
+
+---
+
+## Admonitions
+Admonitions are **intentional and sparse**, not decorative.
+
+Use them to:
+- Highlight irreversible actions
+- Call out one-time decisions
+- Enforce safety boundaries
+
+Common forms:
+```markdown
+!!! warning "Important"
+!!! note
+!!! tip
+!!! success
+```
+
+Do **not** restate obvious information inside admonitions.
+
+---
+
+## Code Blocks (Critical)
+Code blocks are the **primary instructional vehicle**.
+
+### Rules
+- Always fenced
+- Always copy/paste-ready
+- Prefer fewer, larger blocks over many small ones
+- Use inline shell comments (`#`) to explain intent
+
+Example:
+```sh
+# Enable iSCSI service and persist across reboots
+service iscsitarget start
+sysrc iscsitarget_enable=YES
+```
+
+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
+
+---
+
+## Inline Code
+Use backticks for:
+- Dataset names
+- Volume groups
+- Filenames
+- Command names
+- One-off parameters
+
+Example:
+`CLUSTER-STORAGE/iscsi-proxmox`
+
+---
+
+## Lists
+- Use bullet lists for inventories, criteria, and checks
+- Avoid numbered lists for procedures
+- Ordering is conveyed by section layout, not numbering
+
+---
+
+## Diagrams
+- ASCII diagrams only
+- Used to describe hierarchy or flow
+- Must reinforce understanding, not decorate
+
+---
+
+## Validation Sections
+Validation is **mandatory** for any procedure that affects:
+- Storage
+- Networking
+- Virtualization
+- Data integrity
+
+Validation lists should be explicit and testable.
+
+For lower-risk or informational documents, validation is optional.
+
+---
+
+## Tone and Voice
+- Neutral
+- Operational
+- Conservative
+- “Boring is correct”
+
+Avoid:
+- Marketing language
+- Storytelling
+- Over-explanation
+
+---
+
+## Anti-Patterns (Do Not Use)
+- Numbered procedural steps
+- GUI-only workflows when CLI exists
+- Excessive screenshots
+- One-command-per-codeblock sprawl
+- Implicit assumptions
+- Hidden prerequisites
+
+---
+
+## Summary
+Bunny Lab documentation prioritizes:
+- Determinism
+- Safety
+- Reproducibility
+- Auditability
+
+If a step cannot be reproduced from the documentation alone, it is incomplete.