# Automated FAQ Enhancement Guide

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

Complete guide for automated FAQ enhancement: keywords, links, expansion, and condensation.

## Overview

The automated FAQ enhancement system provides one-command FAQ improvement that adds keywords, internal links, expands short answers, condenses long answers, and validates quality.

## Usage

### One-Command Enhancement

```bash
php v2/scripts/blog/automate-faq-enhancement.php --post=slug --category=category
```

**What it does:**
1. Adds keywords to FAQs
2. Adds internal links
3. Expands short answers (<40 words)
4. Condenses long answers (>80 words)
5. Validates quality
6. Generates report

**Options:**
- `--all` - Process all posts
- `--dry-run` - Test without making changes

### Individual Enhancement Scripts

#### Add Keywords

```bash
php v2/scripts/blog/integrate-faq-keywords.php --post=slug --category=category
```

**Features:**
- Extracts primary keyword from post
- Identifies keyword opportunities
- Integrates keywords naturally
- Ensures 50%+ FAQs contain keyword
- Maintains readability

#### Add Links

```bash
php v2/scripts/blog/add-faq-links.php --post=slug --category=category
```

**Features:**
- Matches keywords to link inventory
- Adds 1-2 links per FAQ
- Preserves existing links
- Validates link quality
- Uses German word boundaries

#### Expand Short Answers

```bash
php v2/scripts/blog/expand-short-faq-answers.php
```

**Features:**
- Expands answers <40 words
- Adds context and examples
- Preserves links
- Ensures 40+ words consistently

#### Condense Long Answers

```bash
php v2/scripts/blog/condense-faqs-auto.php
```

**Features:**
- Condenses answers >80 words
- Preserves key information
- Maintains readability
- Targets 60-80 words

## Enhancement Process

### Step 1: Keyword Integration

**How it works:**
1. Extracts primary keyword from post metadata
2. Analyzes each FAQ answer for integration opportunities
3. Adds keyword naturally (not forced)
4. Ensures 50%+ FAQs contain primary keyword

**Example:**
```
Before: "Ein Minijob ist eine geringfügige Beschäftigung."
After: "Ein Minijob ist eine geringfügige Beschäftigung. 
        Bei der Minijob-Abrechnung gibt es Besonderheiten zu beachten."
```

### Step 2: Link Addition

**How it works:**
1. Loads internal link inventory
2. Matches keywords in FAQ answers
3. Adds links contextually (1-2 per FAQ)
4. Preserves existing links
5. Validates link quality

**Link Sources:**
- Common keywords (zeiterfassung, dienstplan, etc.)
- Link inventory from `docs/data/blog-complete-link-inventory.json`
- Post-specific links

### Step 3: Answer Expansion

**How it works:**
1. Identifies answers <40 words
2. Adds context sentences
3. Includes actionable information
4. Preserves original meaning
5. Ensures 40+ words

**Expansion Strategies:**
- Add context about legal requirements
- Include actionable next steps
- Provide additional details
- Maintain natural flow

### Step 4: Answer Condensation

**How it works:**
1. Identifies answers >80 words
2. Preserves first sentence (direct answer)
3. Removes redundant information
4. Maintains key points
5. Targets 60-80 words

**Condensation Strategies:**
- Keep direct answer (10-15 words)
- Preserve key context (20-30 words)
- Remove redundant sentences
- Maintain links and keywords

### Step 5: Quality Validation

**Checks:**
- Word count (40-80 words)
- Keyword presence
- Link quality
- Readability
- Schema validity

## Best Practices

### 1. Review Before Applying

Always review changes:
```bash
# Test with dry-run first
php v2/scripts/blog/automate-faq-enhancement.php --post=slug --category=category --dry-run
```

### 2. Incremental Enhancement

Enhance in stages:
1. Keywords first
2. Links second
3. Expansion/condensation last

### 3. Manual Refinement

Automated enhancement is a starting point:
- Review all changes
- Refine keyword integration
- Verify link relevance
- Adjust answer length if needed

### 4. Quality Validation

Always validate after enhancement:
```bash
php v2/scripts/blog/validate-expansion-quality.php --post=slug --category=category
php v2/scripts/blog/audit-faq-quality.php
```

## Workflow Examples

### New Post Enhancement

```bash
# 1. Generate FAQs
php v2/scripts/blog/generate-faqs-complete.php --post=slug --category=category

# 2. Enhance FAQs
php v2/scripts/blog/automate-faq-enhancement.php --post=slug --category=category

# 3. Validate
php v2/scripts/blog/validate-expansion-quality.php --post=slug --category=category
```

### Existing Post Improvement

```bash
# 1. Check priority
php v2/scripts/blog/prioritize-faq-improvements.php

# 2. Enhance high-priority post
php v2/scripts/blog/automate-faq-enhancement.php --post=slug --category=category

# 3. Re-check quality
php v2/scripts/blog/audit-faq-quality.php
```

### Batch Processing

```bash
# Enhance all posts
php v2/scripts/blog/automate-faq-enhancement.php --all

# Or by category
for post in $(ls v2/data/blog/posts/lexikon/*.json); do
    slug=$(basename $post .json)
    php v2/scripts/blog/automate-faq-enhancement.php --post=$slug --category=lexikon
done
```

## Troubleshooting

### Keywords Not Added

**Check:**
- Primary keyword exists in post metadata
- FAQ answers have integration opportunities
- Keyword not already present

**Solution:** Manually review and add keywords if needed

### Links Not Added

**Check:**
- Link inventory file exists
- Keywords match link inventory
- Links not already present

**Solution:** Review link inventory and add missing links

### Answers Still Too Short/Long

**Check:**
- Expansion/condensation scripts ran successfully
- Word count validation

**Solution:** Run expansion/condensation scripts separately

## Related Documentation

- `FAQ_AUTOMATION_IMPLEMENTATION_SUMMARY.md` - Complete feature overview
- `FAQ_AUTOMATION_QUICK_REFERENCE.md` - Quick command reference
- `FAQ_PRIORITIZATION_GUIDE.md` - Prioritization guide
- `FAQ_BEST_PRACTICES.md` - Content guidelines