# Documentation Structure Guide

**Last Updated:** 2026-01-09

Complete guide to the pages documentation structure, file organization, naming conventions, and maintenance guidelines.

## Directory Structure

```
docs/content/pages/
├── README.md                          # Main overview
├── MASTER_PAGES_INDEX.md             # Complete index with status
├── MASTER_NAVIGATION.md              # Navigation tree
├── DOCUMENTATION_STRUCTURE.md        # This file
├── WEBSITE_AUDIT_REPORT.md           # Website audit results
│
├── homepage/                         # Homepage documentation
│   ├── HOMEPAGE_INVENTORY.md
│   └── homepage-documentation.md
│
├── product-pages/                    # Product feature pages
│   ├── PRODUCT_PAGES_INVENTORY.md
│   ├── ENHANCEMENT_COMPLETE.md
│   └── [product-slug]-documentation.md
│
├── industry-pages/                   # Industry-specific pages
│   ├── INDUSTRY_PAGES_INVENTORY.md
│   ├── ENHANCEMENT_COMPLETE.md
│   └── [industry-slug]-documentation.md
│
├── static-pages/                     # Legal, pricing, company pages
│   ├── STATIC_PAGES_INVENTORY.md
│   ├── pricing-ENHANCEMENT_COMPLETE.md
│   ├── pricing-documentation.md
│   └── [page-slug]-documentation.md
│
├── comparison-pages/                 # SEO comparison pages
│   ├── COMPARISON_PAGES_INVENTORY.md
│   └── [competitor-slug]-documentation.md
│
├── templates-pages/                  # Excel/PDF template pages
│   ├── TEMPLATES_PAGES_INVENTORY.md
│   └── [template-slug]-documentation.md
│
├── download-pages/                   # Gated content pages
│   ├── DOWNLOAD_PAGES_INVENTORY.md
│   └── [download-slug]-documentation.md
│
├── webinar-pages/                    # Event registration pages
│   ├── WEBINAR_PAGES_INVENTORY.md
│   └── [webinar-slug]-documentation.md
│
└── pillar-pages/                     # SEO pillar pages
    ├── PILLAR_PAGES_INVENTORY.md
    └── [pillar-slug]-documentation.md
```

## File Organization Principles

### 1. One Directory Per Page Type

Each page type has its own directory:
- `homepage/` - Homepage files
- `product-pages/` - Product feature pages
- `industry-pages/` - Industry-specific pages
- `static-pages/` - Static pages (legal, pricing, company)
- `comparison-pages/` - Comparison pages
- `templates-pages/` - Template pages
- `download-pages/` - Download pages
- `webinar-pages/` - Webinar pages
- `pillar-pages/` - Pillar pages

### 2. Inventory Files

Each page type directory contains:
- `[PAGE_TYPE]_PAGES_INVENTORY.md` - Complete list of all pages of that type
- Individual page documentation files: `[page-slug]-documentation.md`

### 3. Separation of Concerns

**Important:** Different page types are kept separate:
- **Pricing page** is in `static-pages/`, NOT in `industry-pages/`
- **Industry pages** are in `industry-pages/`, separate from pricing
- Each page type has its own completion/enhancement files

## Naming Conventions

### Inventory Files

- Format: `[PAGE_TYPE]_PAGES_INVENTORY.md`
- Examples:
  - `PRODUCT_PAGES_INVENTORY.md`
  - `STATIC_PAGES_INVENTORY.md`
  - `TEMPLATES_PAGES_INVENTORY.md`

### Page Documentation Files

- Format: `[page-slug]-documentation.md`
- Examples:
  - `pricing-documentation.md`
  - `hospitality-documentation.md`
  - `shiftplan-documentation.md`

### Completion/Enhancement Files

- Format: `[TYPE]-ENHANCEMENT_COMPLETE.md` or `ENHANCEMENT_COMPLETE.md`
- Examples:
  - `pricing-ENHANCEMENT_COMPLETE.md` (in static-pages/)
  - `ENHANCEMENT_COMPLETE.md` (in industry-pages/)

## Cross-Reference Patterns

### Linking Between Page Types

When referencing other page types:
- Use relative paths: `../[page-type]/[file].md`
- Be specific about which page type you're referencing
- Don't lump different page types together

### Example Cross-References

```markdown
## Related Documentation

- [Pricing Page Documentation](../static-pages/pricing-documentation.md)
- [Industry Pages Inventory](../industry-pages/INDUSTRY_PAGES_INVENTORY.md)
- [Product Pages](../product-pages/PRODUCT_PAGES_INVENTORY.md)
```

### Master Index References

All page types should reference:
- `MASTER_PAGES_INDEX.md` - For complete overview
- `README.md` - For main documentation overview

## Documentation Status Tracking

### Status Indicators

- ✅ **Complete** - All pages documented
- ⚠️ **Partial** - Some pages documented
- ❌ **Pending** - No pages documented

### Status Files

Each page type may have:
- `ENHANCEMENT_COMPLETE.md` - Completion summary
- `ENHANCEMENT_SUMMARY.md` - Enhancement status
- `COMPLETION_SUMMARY.md` - Final completion summary

## Maintenance Guidelines

### When Adding New Pages

1. **Add to Inventory**
   - Update `[PAGE_TYPE]_PAGES_INVENTORY.md`
   - Add page entry with status

2. **Create Documentation**
   - Create `[page-slug]-documentation.md`
   - Follow established patterns

3. **Update Master Index**
   - Update `MASTER_PAGES_INDEX.md` counts
   - Update status indicators

4. **Update Cross-References**
   - Update `README.md` if needed
   - Update related inventory files

### When Updating Documentation

1. **Update Last Updated Date**
   - Format: `**Last Updated:** YYYY-MM-DD`
   - Use current date: `date +%Y-%m-%d`

2. **Update Related Files**
   - Update inventory if page structure changed
   - Update master index if status changed

3. **Maintain Cross-References**
   - Verify all links still work
   - Update broken references

### When Separating Page Types

**Important:** If combining different page types in summary files:
1. Split into separate files by page type
2. Update all cross-references
3. Update master index
4. Update README.md

**Example:** Pricing page was separated from industry pages:
- Created `static-pages/pricing-ENHANCEMENT_COMPLETE.md`
- Created `industry-pages/ENHANCEMENT_COMPLETE.md`
- Updated all references

## File Structure Template

### Inventory File Template

```markdown
# [Page Type] Pages Inventory

**Last Updated:** YYYY-MM-DD

Complete inventory of all [page type] pages on the Ordio website.

## [Page Type] Pages (X pages)

1. **[Page Name]** - `[filename].php`
   - **URL:** [URL]
   - **Status:** Published / Draft
   - **Documentation:** ✅ / ⚠️ Pending

## Documentation Status

- ✅ **Documented:** X/Y pages
- ⚠️ **Pending:** Y pages

## Related Documentation

- [Page Type Guides](../../../guides/PAGE_TYPE_GUIDES.md)
- [Cursor Rules](../../../../.cursor/rules/[page-type].mdc)
```

### Page Documentation Template

```markdown
# [Page Name] Page Documentation

**Last Updated:** YYYY-MM-DD

## Basic Information

- **Page Name:** [Full name]
- **Slug:** [URL slug]
- **PHP File:** `v2/pages/[filename].php`
- **URL:** [Full URL]
- **Status:** Published / Draft

## Page Structure

[Document page structure]

## Content Strategy

[Document content strategy]

## Technical Implementation

[Document technical details]

## Related Documentation

- [[Page Type] Inventory](../[page-type]/[PAGE_TYPE]_PAGES_INVENTORY.md)
```

## Best Practices

### Do's

✅ **DO** keep page types separate
✅ **DO** use consistent naming conventions
✅ **DO** update last updated dates
✅ **DO** maintain cross-references
✅ **DO** update master index when status changes
✅ **DO** create inventory files for each page type

### Don'ts

❌ **DON'T** lump different page types together
❌ **DON'T** mix pricing with industry pages
❌ **DON'T** create duplicate inventory files
❌ **DON'T** forget to update cross-references
❌ **DON'T** skip updating master index
❌ **DON'T** use inconsistent naming

## Related Documentation

- **[Master Pages Index](MASTER_PAGES_INDEX.md)** - Complete index
- **[Master Navigation](MASTER_NAVIGATION.md)** - Navigation tree
- **[README.md](README.md)** - Main overview
- **[Website Audit Report](WEBSITE_AUDIT_REPORT.md)** - Audit results