docs/operations/foundations/documentation-styling.md

tags

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:

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