--- tags: - Documentation - Markdown - Style Guide --- ## 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.