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.

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.