# Manual Reviewer Training Guide

**Last Updated:** 2026-01-05

## Documentation Structure

### Automated Reports vs Master Documentation

The documentation system uses a **dual-structure approach**:

1. **Automated Reports** (`data/reports/` folder)

   - Generated automatically by scripts
   - Can be regenerated without affecting manual edits
   - Contains detailed automated analysis
   - Reference these for detailed metrics and data

2. **Master Documentation** (root of post folder)
   - Contains quick summary from reports
   - Includes fully editable manual sections (between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->`)
   - Add your insights and observations here

**Key Principle:** Automated reports provide rich data, master docs provide editable insights. Manual edits in master docs are preserved during regeneration.

## Prioritization System

Posts are prioritized using a comprehensive data-driven scoring system. See `PRIORITIZATION_SYSTEM_GUIDE.md` for details.

**Using Priority Lists:**

- Check `REVIEW_PRIORITY_LIST.md` for prioritized posts
- Review `PRIORITY_DASHBOARD.md` for multiple priority views
- Focus on high priority posts (score ≥ 70) first

**Last Updated:** 2026-01-11

## Overview

This guide provides comprehensive training for manual reviewers conducting blog post documentation reviews. It covers the dual-section documentation system, data-driven recommendations, preservation workflow, and best practices.

## Table of Contents

1. [System Overview](#system-overview)
2. [Documentation Structure](#documentation-structure)
3. [Data-Driven Recommendations](#data-driven-recommendations)
4. [Review Workflow](#review-workflow)
5. [Best Practices](#best-practices)
6. [Common Pitfalls](#common-pitfalls)
7. [Examples](#examples)
8. [Troubleshooting](#troubleshooting)

## System Overview

### What is Manual Review?

Manual review is the process of refining automated documentation with human expertise. The system combines:

- **Automated Analysis:** Data-driven insights from APIs (SISTRIX, GA4, GSC)
- **Human Expertise:** Domain knowledge, content strategy, SEO best practices
- **Preservation System:** Ensures manual edits are never lost during regeneration

### Why Manual Review?

- **Data Context:** Automated data needs human interpretation
- **Business Alignment:** Recommendations must align with business goals
- **Content Quality:** Human judgment ensures content quality
- **SEO Expertise:** Advanced SEO strategies require human insight

### Key Principles

1. **Data-Informed, Not Data-Driven:** Use data as a guide, not a mandate
2. **Preserve Manual Edits:** Always use safe regeneration
3. **Complete Placeholders:** Fill all template placeholders
4. **Document Insights:** Record expert observations
5. **Prioritize Impact:** Focus on high-impact improvements first

## Documentation Structure

### Dual-Section System

Each documentation file uses a dual-section structure:

```
<!-- BEGIN AUTOMATED -->
[Automated content - regenerated by scripts]
<!-- END AUTOMATED -->

<!-- BEGIN MANUAL -->
[Manual content - preserved during regeneration]
<!-- END MANUAL -->
```

### File Types

1. **POST_ANALYSIS.md**

   - Content analysis and quality assessment
   - Search intent alignment
   - SERP features integration
   - Competition analysis

2. **SEO_REPORT.md**

   - SEO performance metrics
   - Keyword analysis
   - Meta tag recommendations
   - Schema markup status

3. **INTERNAL_LINKS.md**

   - Link inventory
   - Domain opportunity-based suggestions
   - Related posts carousel review

4. **IMPROVEMENT_PLAN.md** (Ratgeber/Lexikon only)

   - Actionable recommendations
   - Priority ranking
   - Effort estimates

5. **MANUAL_NOTES.md** (Never overwritten)
   - Comprehensive review notes
   - Expert insights
   - Implementation tracking

### Preservation System

**How It Works:**

1. Before regeneration, manual sections are extracted
2. Automated sections are regenerated with latest data
3. Manual sections are restored after regeneration

**What Gets Preserved:**

- All content in `<!-- BEGIN MANUAL -->` sections
- `MANUAL_NOTES.md` file (never overwritten)
- Manual edits outside markers (if any)

**What Gets Regenerated:**

- Content in `<!-- BEGIN AUTOMATED -->` sections
- Data-driven recommendations
- API-integrated metrics

## Data-Driven Recommendations

### Search Intent Analysis

**What It Is:**

Search intent classification (informational, navigational, transactional) based on SISTRIX data.

**How to Use:**

1. **Review Intent Classification:**

   - Check if primary keyword intent matches content type
   - Verify intent distribution percentages
   - Assess alignment with user goals

2. **Apply Recommendations:**

   - **Informational:** Focus on comprehensive guides, FAQs, structured content
   - **Navigational:** Optimize branding, internal navigation, clear CTAs
   - **Transactional:** Emphasize product/service mentions, conversion paths

3. **Refine in Manual Section:**
   - Add nuanced insights
   - Suggest content adjustments
   - Document intent misalignment if present

**Example:**

```
Automated Section:
Primary Keyword Intent: Informational (85%)
Recommendation: Focus on comprehensive guide format, add FAQs

Manual Section:
Intent Alignment: Good - Content is comprehensive guide
Refinement: Add "How to" section for step-by-step instructions
Consider: Add video tutorial for visual learners
```

### SERP Features Optimization

**What It Is:**

Analysis of SERP features (featured snippets, knowledge panels, PAA boxes) for target keywords.

**How to Use:**

1. **Review SERP Features:**

   - Check if featured snippets are present
   - Identify PAA opportunities
   - Assess knowledge panel eligibility

2. **Apply Recommendations:**

   - **Featured Snippets:** Add concise answers (40-60 words) in first paragraph
   - **PAA Boxes:** Integrate questions as FAQs with direct answers
   - **Knowledge Panels:** Optimize structured data, build authority

3. **Refine in Manual Section:**
   - Suggest specific optimizations
   - Identify content gaps for SERP features
   - Document competitive analysis

**Example:**

```
Automated Section:
Featured Snippets: Not Present
Recommendation: Add concise answer in first paragraph (40-60 words)

Manual Section:
Optimization Strategy: Add definition paragraph after H1
Target Query: "What is [keyword]?"
Answer Format: [Keyword] is [definition]. [Key benefit 1]. [Key benefit 2].
```

### Competition Analysis

**What It Is:**

Keyword competition levels (low, medium, high) based on SISTRIX data.

**How to Use:**

1. **Review Competition Levels:**

   - Identify quick-win keywords (low competition, high volume)
   - Assess medium competition opportunities
   - Evaluate high competition strategies

2. **Apply Recommendations:**

   - **Low Competition:** Prioritize content expansion, quick wins
   - **Medium Competition:** Build authority, comprehensive content
   - **High Competition:** Long-term strategy, niche down, secondary keywords

3. **Refine in Manual Section:**
   - Adjust priorities based on business goals
   - Suggest content depth improvements
   - Document competitive landscape insights

**Example:**

```
Automated Section:
Primary Keyword Competition: Low
Quick-Win Keywords: keyword1, keyword2, keyword3

Manual Section:
Priority Adjustment: Focus on keyword1 first (highest volume)
Content Strategy: Expand existing section on keyword1
Timeline: 2 weeks for content update, 4 weeks for ranking improvement
```

### Domain Opportunities

**What It Is:**

Domain-level keyword opportunities that can be leveraged across posts.

**How to Use:**

1. **Review Domain Opportunities:**

   - Identify posts close to ranking (positions 11-20)
   - Check for cross-post optimization opportunities
   - Assess potential traffic gains

2. **Apply Recommendations:**

   - Suggest content updates for close-to-ranking posts
   - Recommend internal linking strategies
   - Identify content cluster opportunities

3. **Refine in Manual Section:**
   - Prioritize opportunities based on impact
   - Suggest specific content updates
   - Document cross-post strategies

**Example:**

```
Automated Section:
Domain Opportunity: keyword-opportunity (Position: 15, Volume: 500)
Recommendation: Update post to target keyword-opportunity

Manual Section:
Content Update: Add section on keyword-opportunity in existing post
Internal Linking: Add link from related post (post-slug-2)
Expected Impact: +50% traffic if ranking improves to position 5
```

## Review Workflow

### Step 1: Preparation

1. **Check Progress:**

   ```bash
   cat docs/content/blog/REVIEW_PROGRESS_TRACKER.md
   ```

2. **Prioritize Posts:**

   ```bash
   cat docs/content/blog/REVIEW_PRIORITY_LIST.md
   ```

3. **Generate Checklist:**
   ```bash
   php v2/scripts/blog/generate-manual-review-checklist.php --post={slug} --category={category}
   ```

### Step 2: Review Documentation

Navigate to: `docs/content/blog/posts/{category}/{slug}/`

**Review Order:**

1. **MANUAL_REVIEW_CHECKLIST.md** - Personalized checklist
2. **POST_ANALYSIS.md** - Content analysis
3. **SEO_REPORT.md** - SEO performance
4. **INTERNAL_LINKS.md** - Link analysis
5. **IMPROVEMENT_PLAN.md** - Improvement recommendations (Ratgeber/Lexikon only)
6. **MANUAL_NOTES.md** - Comprehensive notes

### Step 3: Complete Placeholders

**Common Placeholders:**

- `{PRIMARY_KEYWORD_1}` → Replace with actual primary keyword
- `{VOLUME_1}` → Replace with SISTRIX volume data
- `{INTENT_ALIGNMENT}` → Assess and document alignment
- `{SEO_HIGH_PRIORITY_1}` → Identify high-priority SEO actions
- `{CONTENT_GAP_1}` → Identify specific content gaps
- `{LINK_OPPORTUNITY_1}` → Suggest strategic internal links

**Search for Placeholders:**

```bash
grep -r "To be\|{.*}" docs/content/blog/posts/{category}/{slug}/*.md
```

### Step 4: Add Manual Insights

**Where to Add:**

- In `<!-- BEGIN MANUAL -->` sections of each file
- In `MANUAL_NOTES.md` for comprehensive notes

**What to Include:**

- Expert observations
- Content strategy insights
- SEO recommendations
- Implementation notes
- Priority adjustments

### Step 5: Validate Quality

```bash
php v2/scripts/blog/validate-documentation-quality.php --post={slug} --category={category}
```

**Expected Output:**

- ✅ Manual sections present
- ✅ Automated sections populated
- ✅ No unpopulated placeholders in automated sections
- ✅ Data integration complete

## Best Practices

### Content Review

1. **Verify Accuracy:**

   - Check factual accuracy
   - Verify current year (use `date +%Y` - currently 2026)
   - Ensure pricing is up-to-date (€89/Standort/Monat)
   - Validate URLs and links

2. **Assess Quality:**

   - Evaluate writing style and tone
   - Check for grammatical errors
   - Ensure readability
   - Verify formatting consistency

3. **Identify Gaps:**
   - Look for missing information
   - Suggest new sections
   - Identify depth opportunities
   - Recommend multimedia integration

### SEO Review

1. **Keyword Strategy:**

   - Verify primary/secondary keywords
   - Suggest alternative keywords
   - Identify long-tail opportunities
   - Refine keyword placement

2. **Meta Data:**

   - Propose engaging meta titles
   - Optimize meta descriptions
   - Ensure keyword inclusion
   - Verify length requirements

3. **Schema Markup:**
   - Identify advanced schema opportunities
   - Suggest HowTo, Product, Review schemas
   - Verify existing schema quality
   - Ensure validation

### Internal Linking Review

1. **Link Quality:**

   - Verify relevance of links
   - Check anchor text optimization
   - Ensure contextual placement
   - Validate link targets

2. **Related Posts:**

   - Evaluate automated suggestions
   - Propose manual overrides if needed
   - Ensure topical relevance
   - Check for content cluster alignment

3. **Cross-Page Type Linking:**
   - Link to tools/calculators
   - Link to templates/downloads
   - Link to product pages
   - Link to comparison pages

### Data-Driven Review

1. **Search Intent:**

   - Verify intent classification accuracy
   - Assess content alignment
   - Suggest content adjustments
   - Document intent misalignment

2. **SERP Features:**

   - Identify optimization opportunities
   - Suggest specific optimizations
   - Document competitive analysis
   - Track implementation progress

3. **Competition:**
   - Prioritize quick-win keywords
   - Assess content depth needs
   - Document competitive landscape
   - Adjust priorities based on business goals

## Common Pitfalls

### Pitfall 1: Overwriting Manual Edits

**Problem:** Manual edits lost during regeneration

**Solution:**

- Always use `safe-regenerate-documentation.php`
- Ensure manual sections are between markers
- Check `MANUAL_NOTES.md` is never overwritten

### Pitfall 2: Ignoring Data-Driven Recommendations

**Problem:** Not leveraging automated insights

**Solution:**

- Review all automated sections
- Understand data context
- Apply recommendations thoughtfully
- Refine in manual sections

### Pitfall 3: Incomplete Placeholder Completion

**Problem:** Placeholders left as "To be..."

**Solution:**

- Use grep to find all placeholders
- Complete systematically
- Verify with validation script
- Document completion in manual notes

### Pitfall 4: Missing Manual Insights

**Problem:** Only completing placeholders, not adding insights

**Solution:**

- Add expert observations
- Document content strategy
- Record SEO recommendations
- Track implementation notes

### Pitfall 5: Not Prioritizing

**Problem:** Treating all improvements equally

**Solution:**

- Use data-driven priority scoring
- Focus on high-impact improvements
- Consider business goals
- Document priority rationale

## Examples

### Example 1: Search Intent Alignment

**Automated Section:**

```
Primary Keyword Intent: Informational (85%)
Secondary Intent: Navigational (10%), Transactional (5%)
Intent Alignment: Good - Content is comprehensive guide
```

**Manual Section:**

```
Intent Refinement:
- Content aligns well with informational intent
- Consider adding navigational elements (clear CTAs to product pages)
- Add transactional elements (product mentions, pricing) for 5% transactional users
- Recommendation: Add "Jetzt testen" CTA in conclusion section
```

### Example 2: SERP Feature Optimization

**Automated Section:**

```
Featured Snippets: Not Present
PAA Boxes: Present (3 questions identified)
Knowledge Panel: Not Present
```

**Manual Section:**

```
SERP Feature Strategy:
1. Featured Snippets:
   - Target Query: "What is [keyword]?"
   - Add definition paragraph after H1 (40-60 words)
   - Use structured format (definition + key points)
   - Timeline: 1 week

2. PAA Boxes:
   - Integrate 3 identified questions as FAQs
   - Use FAQ schema markup
   - Place FAQs after main content
   - Timeline: 2 weeks

3. Knowledge Panel:
   - Optimize structured data (Organization schema)
   - Build authority signals (backlinks, citations)
   - Long-term strategy (3-6 months)
```

### Example 3: Competition-Based Prioritization

**Automated Section:**

```
Primary Keyword Competition: Low
Quick-Win Keywords: keyword1 (Volume: 500, Position: 15), keyword2 (Volume: 300, Position: 12)
```

**Manual Section:**

```
Priority Adjustment:
- Focus on keyword1 first (highest volume, closest to ranking)
- Content Strategy: Expand existing section on keyword1
- Internal Linking: Add link from related post (post-slug-2)
- Expected Impact: +50% traffic if ranking improves to position 5
- Timeline: 2 weeks for content update, 4 weeks for ranking improvement

Keyword2 Strategy:
- Secondary priority (lower volume)
- Content Strategy: Add subsection on keyword2
- Timeline: 4 weeks
```

### Example 4: Domain Opportunity Cross-Referencing

**Automated Section:**

```
Domain Opportunity: keyword-opportunity (Position: 15, Volume: 500)
Recommendation: Update post to target keyword-opportunity
```

**Manual Section:**

```
Cross-Post Strategy:
1. Current Post (post-slug-1):
   - Add section on keyword-opportunity
   - Internal linking from related posts
   - Expected Impact: +30% traffic

2. Related Post (post-slug-2):
   - Add link to current post with keyword-opportunity anchor text
   - Cross-reference in related posts carousel
   - Expected Impact: +20% traffic

3. Content Cluster:
   - Create content cluster around keyword-opportunity
   - Link between related posts
   - Build topical authority
   - Long-term strategy (3-6 months)
```

## Troubleshooting

### Issue: Manual Sections Missing After Regeneration

**Symptoms:** Manual sections disappeared after regeneration

**Solutions:**

1. Check if safe regeneration was used
2. Verify manual section markers are correct
3. Check `preserve-manual-edits.php` logs
4. Restore from backup if needed

### Issue: Placeholders Not Populated

**Symptoms:** Placeholders like `{VOLUME_1}` still present after regeneration

**Solutions:**

1. Verify data files exist: `ls docs/content/blog/posts/{category}/{slug}/data/`
2. Check data file format: `cat docs/content/blog/posts/{category}/{slug}/data/keywords-sistrix.json`
3. Re-run data collection if needed
4. Check script logs for errors

### Issue: Data Integration Incomplete

**Symptoms:** Search intent, SERP features, or competition data missing

**Solutions:**

1. Verify advanced data collection completed:
   ```bash
   ls docs/content/blog/posts/{category}/{slug}/data/search-intent.json
   ls docs/content/blog/posts/{category}/{slug}/data/serp-features.json
   ls docs/content/blog/posts/{category}/{slug}/data/competition-levels.json
   ```
2. Re-run advanced collection if needed:
   ```bash
   php v2/scripts/blog/run-all-advanced-collection.php
   ```
3. Regenerate documentation after collection

### Issue: Overwhelming Amount of Work

**Symptoms:** Too many placeholders, unclear recommendations

**Solutions:**

1. Focus on high-priority posts first
2. Use progress tracker to see incremental progress
3. Complete placeholders systematically
4. Use find/replace for common patterns
5. Review post content directly for clarity

## Quick Reference

### Essential Commands

```bash
# Generate checklist
php v2/scripts/blog/generate-manual-review-checklist.php --post={slug} --category={category}

# Safe regeneration
php v2/scripts/blog/safe-regenerate-documentation.php --post={slug} --category={category}

# Validate quality
php v2/scripts/blog/validate-documentation-quality.php --post={slug} --category={category}

# Find placeholders
grep -r "To be\|{.*}" docs/content/blog/posts/{category}/{slug}/*.md
```

### File Locations

```
docs/content/blog/posts/{category}/{slug}/
├── POST_ANALYSIS.md
├── SEO_REPORT.md
├── INTERNAL_LINKS.md
├── IMPROVEMENT_PLAN.md (Ratgeber/Lexikon only)
├── MANUAL_NOTES.md
├── MANUAL_REVIEW_CHECKLIST.md
└── data/
    ├── keywords-sistrix.json
    ├── performance-ga4.json
    ├── performance-gsc.json
    ├── search-intent.json
    ├── serp-features.json
    └── competition-levels.json
```

### Key Markers

- `<!-- BEGIN AUTOMATED -->` - Start of automated section
- `<!-- END AUTOMATED -->` - End of automated section
- `<!-- BEGIN MANUAL -->` - Start of manual section
- `<!-- END MANUAL -->` - End of manual section

## Related Documentation

- **Manual Review Workflow:** `docs/content/blog/MANUAL_REVIEW_WORKFLOW.md`
- **Data Integration Guide:** `docs/content/blog/DATA_INTEGRATION_GUIDE.md`
- **Cursor Rules:** `.cursor/rules/blog-manual-review.mdc`
- **Implementation Guide:** `docs/content/blog/IMPLEMENTATION_AUTOMATION_GUIDE.md`

## Support

For questions or issues:

1. Check troubleshooting section
2. Review related documentation
3. Check script logs for errors
4. Verify data files exist and are valid

## Version History

- **2026-01-11:** Initial version with dual-section system, data-driven recommendations, and best practices