3.6 KiB
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:
!!! 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:
# 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.