185 lines
3.6 KiB
Markdown
185 lines
3.6 KiB
Markdown
---
|
|
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.
|