Skip to content

Documentation Styling

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: 

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

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.