# How to Use This Blog Documentation System

**Last Updated:** 2026-01-13

## Overview

This guide explains how to navigate and use the blog documentation and rules system effectively. The system is organized to support both human users and AI agents.

## Quick Start

### For New Users

1. **Start Here:** Read [README.md](README.md) for system overview
2. **Check Status:** Review [STATUS.md](STATUS.md) for current system status
3. **Navigate:** Use [MASTER_INDEX.md](MASTER_INDEX.md) for complete navigation
4. **Find Guides:** Check `guides/` directory for how-to guides
5. **Reference:** Check `reference/` directory for technical reference

### For AI Agents

1. **Rule Discovery:** Check `.cursor/rules/blog-*.mdc` files for blog-specific rules
2. **Documentation Mapping:** Use `MASTER_INDEX.md` to find relevant documentation
3. **Cross-References:** Follow "See Also" sections in documentation
4. **Scripts:** Check `SCRIPTS_INVENTORY.md` for available scripts

## Directory Structure

```
docs/content/blog/
├── README.md                    # System overview
├── STATUS.md                    # Current system status
├── MASTER_INDEX.md              # Complete navigation
├── guides/                      # How-to guides and workflows
│   ├── DATA_COLLECTION_GUIDE.md
│   ├── MANUAL_REVIEW_WORKFLOW.md
│   ├── TEMPLATE_DEVELOPMENT_GUIDE.md
│   └── ...
├── reference/                   # Technical reference
│   ├── COMPONENT_API.md
│   ├── DATA_STRUCTURE_MAPPING.md
│   └── ...
├── posts/                       # Post-specific documentation
│   └── {category}/{slug}/
└── archive/                     # Historical files
    └── (archive removed - historical files redundant with STATUS.md)
```

## Finding Documentation

### By Task Type

**Data Collection:**

- [Data Collection Guide](guides/DATA_COLLECTION_GUIDE.md)
- [Data Integration Guide](guides/DATA_INTEGRATION_GUIDE.md)
- [Troubleshooting Data Collection](guides/TROUBLESHOOTING_DATA_COLLECTION.md)

**Manual Review:**

- [Manual Review Workflow](guides/MANUAL_REVIEW_WORKFLOW.md)
- [Manual Reviewer Training Guide](guides/MANUAL_REVIEWER_TRAINING_GUIDE.md)
- [Post Review Checklist](POST_REVIEW_CHECKLIST.md)

**Template Development:**

- [Template Development Guide](guides/TEMPLATE_DEVELOPMENT_GUIDE.md)
- [Component API](reference/COMPONENT_API.md)
- [Data Structure Mapping](reference/DATA_STRUCTURE_MAPPING.md)

**Backup & Restoration:**

- [Backup Guide](guides/BACKUP_GUIDE.md)
- [Backup Process](guides/BACKUP_PROCESS.md)
- [Restoration Guide](guides/RESTORATION_GUIDE.md)

### By File Type

**Status Files:**

- `STATUS.md` - Current system status (single source of truth)
- Historical status files archived in `archive/`

**Implementation Guides:**

- `IMPLEMENTATION_ACTION_PLAN.md` - Week-by-week plan
- `QUICK_WINS_IMPLEMENTATION_GUIDE.md` - Top opportunities
- `DATA_DRIVEN_IMPROVEMENTS.md` - Strategy guide

**Review Resources:**

- `REVIEW_PRIORITY_LIST.md` - Prioritized posts
- `REVIEW_PROGRESS_TRACKER.md` - Progress tracking
- `CONTENT_GAPS_SUMMARY.md` - Content gap analysis

## Using Cursor Rules

### Finding Relevant Rules

Blog-related rules are in `.cursor/rules/blog-*.mdc`:

- `blog-backup.mdc` - Backup requirements
- `blog-cta-patterns.mdc` - CTA patterns
- `blog-data-collection.mdc` - Data collection rules
- `blog-index-hero.mdc` - Index page patterns
- `blog-manual-review.mdc` - Manual review rules
- `blog-post-documentation.mdc` - Documentation requirements
- `blog-templates.mdc` - Template patterns

### Rule Structure

Each rule file contains:

- YAML frontmatter (description, globs, relatedRules, relatedDocs)
- Overview section
- When to use section
- Patterns and examples
- Related documentation references

## Using Scripts

### Finding Scripts

Check `SCRIPTS_INVENTORY.md` for complete script catalog organized by:

- Category (data-collection, analysis, generation, validation, etc.)
- Language (PHP, Python)
- Purpose

### Common Scripts

**Data Collection:**

- `run-all-data-collection.php` - Master collection script
- `collect-post-keywords-sistrix.php` - SISTRIX keywords
- `collect-post-performance-ga4.php` - GA4 metrics

**Documentation:**

- `generate-post-documentation.php` - Generate docs
- `safe-regenerate-documentation.php` - Safe regeneration
- `validate-post-documentation.php` - Validate docs

**Analysis:**

- `analyze-post-content.php` - Content analysis
- `analyze-post-seo.php` - SEO analysis
- `analyze-post-links.php` - Link analysis

## Navigation Patterns

### From Rules to Documentation

1. Check rule's `relatedDocs` in YAML frontmatter
2. Follow "Related Documentation" section at end of rule
3. Use `MASTER_INDEX.md` for comprehensive navigation

### From Documentation to Rules

1. Check "Related Cursor Rules" section (if present)
2. Use rule name pattern: `blog-{topic}.mdc`
3. Check `.cursor/rules/README.md` for rule index

### From Scripts to Documentation

1. Check script header comments for documentation references
2. Use `SCRIPTS_INVENTORY.md` for script catalog
3. Check guides for script usage examples

## Best Practices

### For Human Users

1. **Start with Overview:** Always read `README.md` and `STATUS.md` first
2. **Use Master Index:** `MASTER_INDEX.md` is your navigation hub
3. **Follow Guides:** Use `guides/` directory for step-by-step instructions
4. **Check Reference:** Use `reference/` directory for technical details
5. **Keep Updated:** Check `STATUS.md` for current system status

### For AI Agents

1. **Rule Discovery:** Match file paths to rule glob patterns
2. **Documentation Discovery:** Use `MASTER_INDEX.md` and "See Also" sections
3. **Cross-Reference:** Follow bidirectional links (rules ↔ docs)
4. **Script Discovery:** Use `SCRIPTS_INVENTORY.md` for script catalog
5. **Validation:** Use validation scripts before making changes

## Troubleshooting

### Can't Find Documentation

1. Check `MASTER_INDEX.md` for complete navigation
2. Search `DOCUMENTATION_INVENTORY.md` for file catalog
3. Check `guides/` and `reference/` directories
4. Review `OPTIMIZATION_SUMMARY.md` for structure overview

### Broken Links

1. Run `validate-links.py --fix` to check and fix links
2. Check `LINK_VALIDATION_REPORT.json` for broken links
3. Verify file moved to `guides/` or `reference/` directories

### Rule Not Applying

1. Check rule glob patterns match file path
2. Verify rule YAML frontmatter is valid
3. Run `validate-blog-rules.py` to check rule validity
4. Check `RULES_VALIDATION_REPORT.md` for issues

### Script Not Found

1. Check `SCRIPTS_INVENTORY.md` for script catalog
2. Verify script exists in `v2/scripts/blog/`
3. Check script has proper header documentation

## Maintenance

### Adding New Documentation

1. **Guides:** Add to `guides/` directory
2. **Reference:** Add to `reference/` directory
3. **Status:** Update `STATUS.md` (don't create new status files)
4. **Index:** Update `MASTER_INDEX.md` with new file
5. **Cross-Reference:** Add "See Also" sections

### Updating Rules

1. Update rule content
2. Update "Last Updated" date
3. Update `relatedDocs` if needed
4. Run `validate-blog-rules.py` to verify
5. Update `MASTER_INDEX.md` if structure changes

### Historical Files

1. Historical completion summaries are not archived (redundant with STATUS.md)
2. Current state is always in STATUS.md
3. Change history is preserved in CHANGELOG.md
4. Keep only current status in root directory

## Related Documentation

- [README.md](README.md) - System overview
- [STATUS.md](STATUS.md) - Current status
- [MASTER_INDEX.md](MASTER_INDEX.md) - Complete navigation
- [OPTIMIZATION_SUMMARY.md](OPTIMIZATION_SUMMARY.md) - Optimization details
- [CHANGELOG.md](CHANGELOG.md) - Change history

## Support

For questions or issues:

1. Check relevant guide in `guides/` directory
2. Review troubleshooting sections in guides
3. Check `MASTER_INDEX.md` for navigation
4. Review `OPTIMIZATION_SUMMARY.md` for system overview