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:

```markdown
# 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:

```markdown
## 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:**
```markdown
Use `backticks` for inline code, commands, and file names.
```

**Code Blocks:**
````markdown
```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`:

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

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

### Lists

**Unordered Lists:**
```markdown
- Item 1
- Item 2
  - Sub-item 2.1
  - Sub-item 2.2
```

**Ordered Lists:**
```markdown
1. Step 1
2. Step 2
3. Step 3
```

**Task Lists:**
```markdown
- [ ] Task 1
- [x] Completed task
- [ ] Task 3
```

### Tables

**Format:**
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
```

**Alignment:**
- Left: Default
- Center: `:---:`
- Right: `---:`

### Links

**Internal Links:**
```markdown
[Link Text](../02-architecture/NETWORK_ARCHITECTURE.md)
[Link Text](../02-architecture/NETWORK_ARCHITECTURE.md#section)
```

**External Links:**
```markdown
[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:**
```markdown
# Check Proxmox cluster status
pvecm status

# Expected output:
# Cluster information
# ...
```

**Warnings and Notes:**
```markdown
> **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:**
```markdown
See **[TROUBLESHOOTING_FAQ](../09-troubleshooting/TROUBLESHOOTING_FAQ.md)** for more information.
```

**Examples:**
```markdown
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:

```markdown
## 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:

```markdown
## 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

```markdown
# 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

```bash
# Edit network configuration
nano /etc/network/interfaces
```

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

## Related Documentation

- **[NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md)** - Network architecture
- **[TROUBLESHOOTING_FAQ.md](../09-troubleshooting/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