# FAQ Maintenance Guide

**Last Updated:** 2026-01-14

Complete guide for maintaining FAQ quality, identifying and fixing duplicates, and preventing future issues.

## Overview

This guide provides step-by-step instructions for:
1. Identifying duplicate FAQs
2. Fixing duplicate FAQs manually
3. Best practices for FAQ updates
4. Quality standards
5. Validation procedures

## Identifying Duplicate FAQs

### Automated Detection

**Run comprehensive analysis:**
```bash
php v2/scripts/blog/analyze-faq-duplicates.php
```

**Output:** `docs/content/blog/FAQ_DUPLICATE_ANALYSIS.md`

**What it detects:**
- Posts with multiple FAQ wrappers
- Posts with duplicate questions (exact matches)
- Posts with similar questions (fuzzy matching)
- Posts with repetitive answer endings
- Answer quality issues

### Manual Detection

**Check for multiple wrappers:**
```bash
grep -c '<div class="schema-faq wp-block-yoast-faq-block">' v2/data/blog/posts/{category}/{slug}.json
```
Should return `1` (one wrapper only).

**Check for duplicate questions:**
```bash
php -r "require_once 'v2/config/blog-template-helpers.php'; \$data = json_decode(file_get_contents('v2/data/blog/posts/{category}/{slug}.json'), true); \$faqs = extract_faqs_from_html(\$data['content']['html']); \$questions = array_column(\$faqs, 'question'); echo 'Total: ' . count(\$questions) . ', Unique: ' . count(array_unique(\$questions));"
```

## Fixing Duplicate FAQs

### Automated Fix

**Deduplicate all posts:**
```bash
php v2/scripts/blog/deduplicate-faqs.php --all --backup
```

**Deduplicate single post:**
```bash
php v2/scripts/blog/deduplicate-faqs.php --post=slug --category=category --backup
```

**Dry run (preview changes):**
```bash
php v2/scripts/blog/deduplicate-faqs.php --all --dry-run
```

**What it does:**
- Removes duplicate FAQ sections (keeps first occurrence)
- Merges multiple FAQ wrappers into single wrapper
- Removes duplicate questions (exact and fuzzy matching)
- Keeps best answer when duplicates exist
- Removes boilerplate/repetitive answer endings
- Creates backups before changes

### Manual Fix

1. **Open post JSON file:** `v2/data/blog/posts/{category}/{slug}.json`
2. **Find FAQ sections:** Search for `<div class="schema-faq wp-block-yoast-faq-block">`
3. **Identify duplicates:** Look for repeated questions
4. **Remove duplicates:** Keep first occurrence, remove subsequent duplicates
5. **Merge wrappers:** If multiple wrappers exist, merge into single wrapper
6. **Validate:** Run validation script to verify fix

## Best Practices for FAQ Updates

### Before Adding FAQs

1. **Check existing FAQs:**
   ```bash
   php -r "require_once 'v2/config/blog-template-helpers.php'; \$data = json_decode(file_get_contents('v2/data/blog/posts/{category}/{slug}.json'), true); \$faqs = extract_faqs_from_html(\$data['content']['html']); print_r(\$faqs);"
   ```

2. **Use add-faqs-to-post.php script:**
   ```bash
   php v2/scripts/blog/add-faqs-to-post.php --post=slug --category=category --faqs=faqs.json
   ```
   This script automatically checks for existing FAQs and prevents duplicates.

### When Updating FAQs

1. **Never append:** Don't add new FAQ wrapper - merge with existing FAQs
2. **Check for duplicates:** Normalize questions for comparison
3. **Remove boilerplate:** Avoid generic endings
4. **Validate before saving:** Run validation script

### Quality Standards

**Answer Length:** 40-80 words per answer
- Too short (< 40): Expand with context
- Too long (> 80): Condense to key points

**No Boilerplate:** Remove generic endings like:
- "Diese Informationen sind wichtig für die korrekte Umsetzung..."
- "Bei Fragen oder Unsicherheiten empfiehlt es sich..."

**Direct Answers:** First sentence should directly answer the question (10-15 words)

## Validation Procedures

### Pre-Publication Checklist

1. **Run deduplication check:**
   ```bash
   php v2/scripts/blog/deduplicate-faqs.php --all --dry-run
   ```

2. **Run quality improvement:**
   ```bash
   php v2/scripts/blog/improve-faq-answers.php --all --dry-run
   ```

3. **Validate schema:**
   ```bash
   php v2/scripts/blog/validate-faq-schema.php --all
   ```

4. **Check for issues:**
   - No duplicate questions
   - Single FAQ wrapper per post
   - Answer length 40-80 words
   - No boilerplate text
   - Valid FAQPage schema

### Regular Maintenance

**Monthly:**
- Run deduplication script on all posts
- Review quality audit report
- Fix any issues found

**Quarterly:**
- Comprehensive analysis of all FAQs
- Review and update quality standards
- Update documentation if needed

## Troubleshooting

### FAQs Not Extracting

**Check HTML structure:**
- Verify FAQ wrapper exists: `<div class="schema-faq wp-block-yoast-faq-block">`
- Verify FAQ sections exist: `<div class="schema-faq-section">`
- Verify question format: `<strong class="schema-faq-question">`
- Verify answer format: `<p class="schema-faq-answer">`

### Duplicates Still Showing

**Check extraction function:**
- `extract_faqs_from_html()` automatically deduplicates
- Check error logs for deduplication warnings
- Verify HTML doesn't have multiple wrappers

### Schema Validation Fails

**Check:**
- All FAQs included in schema
- Answers match HTML (word-for-word, HTML stripped)
- No HTML links in schema answers
- Valid JSON syntax

## Related Documentation

- `docs/content/blog/FAQ_WORKFLOW.md` - Complete FAQ workflow
- `docs/content/blog/FAQ_BEST_PRACTICES.md` - Best practices guide
- `.cursor/rules/blog-faq-optimization.mdc` - Cursor rules
- `docs/content/blog/FAQ_DUPLICATE_ANALYSIS.md` - Latest analysis report