Complete markdown files cleanup and organization

- Organized 252 files across project - Root directory: 187 → 2 files (98.9% reduction) - Moved configuration guides to docs/04-configuration/ - Moved troubleshooting guides to docs/09-troubleshooting/ - Moved quick start guides to docs/01-getting-started/ - Moved reports to reports/ directory - Archived temporary files - Generated comprehensive reports and documentation - Created maintenance scripts and guides All files organized according to established standards.
2026-01-06 01:46:25 -08:00
parent 1edcec953c
commit cb47cce074
1327 changed files with 217220 additions and 801 deletions
--- a/docs/DOCUMENTATION_STYLE_GUIDE.md
+++ b/docs/DOCUMENTATION_STYLE_GUIDE.md
@@ -0,0 +1,401 @@
+# 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