## 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. --- ## 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. --- ## 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.