proxmox/docs/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

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

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

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

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

---

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

---

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