proxmox/docs/00-meta/DOCUMENTATION_STYLE_GUIDE.md

Documentation Style Guide

Last Updated: 2025-01-20
Document Version: 1.0
Status: Active Documentation

---

Overview

This style guide establishes standards for documentation in the Proxmox project, ensuring consistency, clarity, and maintainability across all documentation.

---

File Naming Convention

Standard Format

Format: UPPERCASE_WITH_UNDERSCORES.md

Examples:

• ✅ NETWORK_ARCHITECTURE.md
• ✅ DEPLOYMENT_GUIDE.md
• ✅ TROUBLESHOOTING_FAQ.md
• ❌ network-architecture.md (incorrect)
• ❌ deploymentGuide.md (incorrect)

Exceptions

• README.md - Standard convention (lowercase)
• MASTER_INDEX.md - Master index file

---

Document Structure

Standard Header

Every document should start with:

# Document Title

**Last Updated:** YYYY-MM-DD  
**Document Version:** X.Y  
**Status:** Active Documentation / Archived / Draft

---

Table of Contents

For documents longer than 500 lines, include a table of contents:

## Table of Contents

1. [Section 1](#section-1)
2. [Section 2](#section-2)
3. [Section 3](#section-3)

---

Markdown Standards

Headings

Hierarchy:

• # - Document title (H1)
• ## - Major sections (H2)
• ### - Subsections (H3)
• #### - Sub-subsections (H4)

Guidelines:

• Use H1 only for document title
• Don't skip heading levels (H2 → H4)
• Use descriptive headings

Code Blocks

Inline Code:

Use `backticks` for inline code, commands, and file names.

Code Blocks:

```bash
# Use language identifier
command --option value
```

Supported Languages:

• bash - Shell commands
• yaml - YAML files
• json - JSON files
• python - Python code
• javascript - JavaScript code
• markdown - Markdown examples

Expected output: For command examples, include expected output where it helps (e.g. success message, sample JSON). Either:

• Inline comment in the block: # Expected: Cluster name, quorum, node list
• Or a following block with language text:

```bash
pvecm status
```
Expected: Cluster name, quorum, node list.

```bash
pct list
```
Expected: Table of VMID, status, name, type.

Lists

Unordered Lists:

- Item 1
- Item 2
  - Sub-item 2.1
  - Sub-item 2.2

Ordered Lists:

1. Step 1
2. Step 2
3. Step 3

Task Lists:

- [ ] Task 1
- [x] Completed task
- [ ] Task 3

Tables

Format:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

Alignment:

• Left: Default
• Center: :---:
• Right: ---:

Links

Internal Links:

[Link Text](../02-architecture/NETWORK_ARCHITECTURE.md)
[Link Text](../02-architecture/NETWORK_ARCHITECTURE.md#section)

External Links:

[Link Text](https://example.com)

Emphasis

• Bold: **text** - For important terms, warnings
• Italic: *text* - For emphasis, variable names
• Code: `text` - For commands, file names, code

---

Content Guidelines

Writing Style

1. Clarity:

   • Use clear, concise language
   • Avoid jargon when possible
   • Define technical terms

2. Tone:

   • Professional but approachable
   • Direct and actionable
   • Helpful and informative

3. Structure:

   • Logical flow
   • Progressive detail
   • Clear sections

Technical Content

Commands:

• Show complete commands
• Include expected output
• Explain what commands do

Examples:

# Check Proxmox cluster status
pvecm status

# Expected output:
# Cluster information
# ...

Warnings and Notes:

> **Warning:** This action cannot be undone.

> **Note:** This feature requires Proxmox VE 8.0 or later.

---

Document Types

Getting Started Guides

Structure:

1. Overview
2. Prerequisites
3. Step-by-step instructions
4. Verification
5. Next steps

Configuration Guides

Structure:

1. Overview
2. Prerequisites
3. Configuration steps
4. Verification
5. Troubleshooting

Troubleshooting Guides

Structure:

1. Problem description
2. Symptoms
3. Solutions (ordered by likelihood)
4. Prevention
5. Related documentation

Reference Documents

Structure:

1. Overview
2. Reference tables
3. Examples
4. Related documentation

---

Cross-References

Linking to Other Documents

Format:

See **[TROUBLESHOOTING_FAQ](../09-troubleshooting/TROUBLESHOOTING_FAQ.md)** for more information.

Examples:

For network architecture details, see **[NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md)**.

See also:
- **[ORCHESTRATION_DEPLOYMENT_GUIDE.md](../02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md)** - Deployment procedures
- **[TROUBLESHOOTING_FAQ.md](../09-troubleshooting/TROUBLESHOOTING_FAQ.md)** - Troubleshooting

Related Documentation Section

Every document should end with:

## Related Documentation

- **[MASTER_INDEX](../MASTER_INDEX.md)** - Documentation index
- **[TROUBLESHOOTING_FAQ](../09-troubleshooting/TROUBLESHOOTING_FAQ.md)** - FAQ
- **[MASTER_INDEX.md](../MASTER_INDEX.md)** - Complete documentation index

---

Version Control

Document Versioning

Format: X.Y

• X - Major version (breaking changes, major rewrites)
• Y - Minor version (updates, additions)

Examples:

• 1.0 - Initial version
• 1.1 - Minor updates
• 2.0 - Major rewrite

Change Log

For significant documents, include a change log:

## Change Log

### Version 2.0 (2025-01-20)
- Complete rewrite
- Added new sections
- Updated procedures

### Version 1.1 (2024-12-15)
- Updated network configuration
- Added troubleshooting section

### Version 1.0 (2024-11-01)
- Initial version

---

Review and Maintenance

Review Cycle

• Critical Documents: Monthly
• Standard Documents: Quarterly
• Reference Documents: As needed

Update Process

1. Review: Check for outdated information
2. Update: Make necessary changes
3. Version: Update version number
4. Date: Update last updated date
5. Review: Have another team member review

Documentation Testing (Optional)

To verify documentation accuracy:

1. Commands: Run shell commands in a safe environment (e.g. read-only or test host) and confirm output matches or is consistent with documented expected output.
2. Paths and links: Use docs/scripts/check-docs-links.sh (or markdown-link-check/lychee) to find broken links; fix docs-internal and root links first.
3. Headers: Run docs/scripts/validate-doc-headers.sh to ensure Last Updated, Status, and --- are present; add Document Version where missing.
4. Cross-references: Run docs/scripts/check-docs-crossrefs.sh to list docs missing a Related Documentation section; add cross-refs where appropriate.
5. Procedures: For step-by-step guides, perform the procedure once in a test environment and update steps or expected output if they diverge.

---

Examples

Good Documentation

# Network Configuration Guide

**Last Updated:** 2025-01-20  
**Document Version:** 1.0  
**Status:** Active Documentation

---

## Overview

This guide explains how to configure network settings for Proxmox hosts.

## Prerequisites

- Proxmox VE 8.0 or later
- Root access to Proxmox host
- Network interface information

## Configuration Steps

### Step 1: Identify Network Interface

```bash
# List network interfaces
ip addr show

Step 2: Edit Network Configuration

# Edit network configuration
nano /etc/network/interfaces

Warning: Incorrect network configuration can cause loss of network connectivity.

Related Documentation

• NETWORK_ARCHITECTURE.md - Network architecture
• TROUBLESHOOTING_FAQ.md - Troubleshooting

---

Last Updated: 2025-01-20
Review Cycle: Quarterly

---

## Checklist

Before submitting documentation:

- [ ] File name follows convention
- [ ] Standard header included
- [ ] Table of contents (if needed)
- [ ] Code blocks have language identifiers
- [ ] Links are correct and working
- [ ] Related documentation section included
- [ ] Version and date updated
- [ ] Reviewed for clarity and accuracy

---

## Review Schedule

| Frequency | Scope | Actions |
|-----------|--------|---------|
| **Quarterly** | Architecture and design documents (02-architecture, 05-network, 11-references/NETWORK_CONFIGURATION_MASTER) | Review for accuracy; sync directory trees in MASTER_INDEX and docs/README; run link validation. |
| **Monthly** | Operational runbooks (03-deployment, 09-troubleshooting) | Update procedures; verify commands and paths. |
| **As needed** | Troubleshooting, quick references | Update when procedures or endpoints change. |

---

## Document Versioning and Dates

- **Last Updated:** Use ISO format `YYYY-MM-DD` (e.g. 2026-01-31).
- **Document Version:** Use `X.Y` (e.g. 1.0, 1.1). Bump minor for non-breaking edits; consider major for structural changes.
- **Status:** Use one of: `Active Documentation`, `Archived`, `Draft`. Do not use emoji in the status field; keep emoji in body content if desired.

**Optional document status indicators (visual):** You may add a single emoji before or after the Status line for quick scanning:
- 🟢 **Active** – Active Documentation
- 📁 **Archived** – Archived
- 📝 **Draft** – Draft
- ⚠️ **Deprecated** – Being phased out

Example: `**Status:** 🟢 Active Documentation` or `**Status:** Active Documentation 🟢`. Use sparingly and consistently (e.g. only in MASTER_INDEX or key entry-point docs).
- Update "Last Updated" and optionally "Document Version" whenever you make substantive edits.

---

## Link and Header Validation

- **Link validation:** Use `markdown-link-check` or `lychee` to find broken links. Run periodically (e.g. from `docs/` or repo root). See [DOCUMENTATION_FIX_TASK_LIST.md](DOCUMENTATION_FIX_TASK_LIST.md) for report references.
- **Header validation:** Use `docs/scripts/validate-doc-headers.sh` (if present) to check that documents have standard headers (Last Updated, Document Version, Status, `---`).
- **Cross-references:** Use `docs/scripts/check-docs-crossrefs.sh` (optional) to list docs that may be missing a "Related Documentation" section; add cross-refs manually where appropriate.

---

## Optional: Accessibility and Output Formats

- **Print-friendly / PDF:** Key docs can be exported to PDF (e.g. via Pandoc, VS Code Markdown PDF, or browser Print to PDF). Prefer single-column layout and avoid wide tables where possible.
- **Mobile-friendly:** Keep paragraphs and tables concise; use collapsible sections in long docs if your renderer supports it. Test key pages on small viewports.
- **Dark mode:** Optional dark theme for rendered docs (e.g. MkDocs with readthedocs theme, or CSS `prefers-color-scheme: dark`). Not required; apply consistently if adopted.

---

## Optional: Screenshots and Images

- **When to use:** Add screenshots where they materially help (e.g. UI wizards, dashboard layouts, error dialogs). Prefer text + code for procedures.
- **Where to store:** Use `docs/assets/` or a per-doc folder (e.g. `docs/04-configuration/cloudflare/screenshots/`). Reference with relative paths.
- **Naming:** Use descriptive names: `omada-vlan-config.png`, `proxmox-storage-summary.png`. Keep file size reasonable (compress if needed).

---

## Optional: Diagrams and Visual Aids

- **Automated diagram generation:** For config-driven diagrams, consider: Mermaid CLI (`mmdc`), Structurizr, or custom scripts that emit Mermaid/PlantUML. Evaluate per use case; hand-maintained Mermaid in-doc is often sufficient.
- **Service state machines:** Optional state diagrams for key services (e.g. container lifecycle: created → running → stopped). Use Mermaid `stateDiagram-v2` or a short ASCII flow.
- **ASCII art diagrams:** For terminals or minimal dependencies, simple ASCII diagrams are acceptable (e.g. `[Client] --> [NGINX] --> [Backend]`). Prefer Mermaid for version-controlled, editable diagrams.
- **Visual table of contents:** In long docs, optional priority/status indicators in the TOC (e.g. 🟢 Active, 📁 Archived) can aid scanning; use sparingly and consistently.
- **Document relationship map:** An optional high-level diagram of doc relationships (e.g. MASTER_INDEX → category READMEs → key docs) lives in [DOCUMENT_RELATIONSHIP_MAP.md](DOCUMENT_RELATIONSHIP_MAP.md).

---

**Last Updated:** 2026-01-31  
**Review Cycle:** Quarterly