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

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](../path/to/file.md)
[Link Text](../path/to/file.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 **[Document Name](path/to/document.md)** for more information.

Examples:

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

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

Related Documentation Section

Every document should end with:

## Related Documentation

- **[Related Doc 1](path/to/doc1.md)** - Description
- **[Related Doc 2](path/to/doc2.md)** - Description
- **[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

---

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

---

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