proxmox/docs/CONTRIBUTOR_GUIDELINES.md

Contributor Guidelines

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

---

Overview

This document provides guidelines for contributing to the documentation, including style standards, review process, and approval workflow.

---

Style Guide Reference

Primary Reference:

• DOCUMENTATION_STYLE_GUIDE.md ⭐⭐⭐

Key Standards:

• File naming: UPPERCASE_WITH_UNDERSCORES.md
• Headers: Include Last Updated, Document Version, Status
• Cross-references: Use Related Documentation sections
• Code blocks: Include language identifiers and expected output

---

Contribution Process

Step 1: Identify Need

Ways to contribute:

• Fix errors or outdated information
• Add missing documentation
• Improve existing documentation
• Add examples or use cases
• Create diagrams or visualizations

---

Step 2: Follow Standards

Before contributing:

1. Read DOCUMENTATION_STYLE_GUIDE.md
2. Review similar documents for consistency
3. Use templates where available
4. Follow naming conventions

---

Step 3: Create/Update Document

For new documents:

• Use appropriate directory structure
• Follow style guide header format
• Include Related Documentation section
• Add to MASTER_INDEX.md

For updates:

• Update Last Updated date
• Increment Document Version if significant changes
• Update change log if document has one
• Verify all links still work

---

Step 4: Review and Test

Self-review checklist:

• Follows style guide
• All links work
• Code examples tested (if applicable)
• No placeholder content
• Proper cross-references
• Added to index files

---

Step 5: Submit for Review

Review process:

1. Create pull request or notify team
2. Include description of changes
3. Reference related issues/tasks
4. Wait for review approval

---

Approval Workflow

Review Levels

Level 1: Self-Review

• Minor corrections
• Formatting fixes
• Link updates

Level 2: Peer Review

• New documents
• Significant updates
• Configuration changes

Level 3: Team Review

• Architecture changes
• Major procedure changes
• Policy updates

---

Examples and Templates

New Document Template

# Document Title

**Navigation:** [Home](01-getting-started/README.md) > [Category](01-getting-started/README.md) > Document Title

**Last Updated:** YYYY-MM-DD  
**Document Version:** 1.0  
**Status:** 🟢 Active Documentation

---

## Overview

[Document purpose and scope]

---

[Content sections]

---

## Related Documentation

- **[Related Doc 1](path/to/doc1.md)** ⭐⭐⭐ - Description
- **[Related Doc 2](path/to/doc2.md)** ⭐⭐ - Description

---

**Last Updated:** YYYY-MM-DD  
**Review Cycle:** [Monthly/Quarterly/As Needed]

---

Common Contribution Types

Adding Examples

Guidelines:

• Use real-world scenarios
• Include expected outputs
• Test examples before documenting
• Update if procedures change

---

Fixing Errors

Process:

1. Identify error
2. Verify correct information
3. Update document
4. Update related documents if needed
5. Test fix

---

Adding Diagrams

Guidelines:

• Use Mermaid for new diagrams
• Follow diagram standards
• Reference in text
• Update visual index

---

Related Documentation

• DOCUMENTATION_STYLE_GUIDE.md ⭐⭐⭐ - Style guide
• MASTER_INDEX.md ⭐⭐⭐ - Documentation index
• MAINTENANCE_REVIEW_SCHEDULE.md ⭐ - Review schedule

---

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