# FAQ Workflow Documentation

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

Complete workflow documentation for FAQ creation, optimization, and maintenance for blog posts.

## Overview

This document provides step-by-step workflows for:

1. Creating FAQs for posts from scratch (fresh start approach)
2. Optimizing existing FAQs
3. Maintaining FAQ quality over time
4. Managing SISTRIX credit usage
5. Integrated FAQ planning in content creation workflow

**Note:** FAQs are stored in the `faqs` array in post JSON files, NOT in HTML content. The template renders FAQs separately via `BlogFAQ.php` component.

## Quick Start: Integrated Workflow

For new posts, use the integrated workflow that combines FAQ planning with content creation:

**Complete FAQ Generation (Recommended):**

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

This single command:

- Generates FAQ questions
- Generates FAQ answers (AI-powered)
- Adds keywords automatically
- Adds internal links automatically
- Validates quality

**See:** `CONTENT_CREATION_WORKFLOW.md` for complete workflow guide.

## Workflow 1: Creating FAQs for New Posts

### Step 1: Prioritize Posts

**Script:** `v2/scripts/blog/prioritize-faq-gaps.php`

```bash
php v2/scripts/blog/prioritize-faq-gaps.php
```

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

**Result:** Priority-ordered list of posts without FAQs, sorted by category and traffic potential.

### Step 2: Collect Research Data

**Script:** `v2/scripts/blog/collect-faq-research-data.php`

**For single post:**

```bash
php v2/scripts/blog/collect-faq-research-data.php --post=slug --category=category
```

**For multiple posts:**

```bash
php v2/scripts/blog/collect-faq-research-data.php --all --limit=10
```

**What it collects:**

- People Also Ask questions from `paa-questions.json` (keyword.questions) or `serp-features.json` (keyword.seo.serpfeatures returns count only; run `collect-post-paa-questions.php` first for actual question text)
- Top GSC queries from `performance-gsc.json`
- Related keywords from `keywords-sistrix.json`
- SERP features data

**PAA sources:** Run `collect-post-paa-questions.php` before FAQ research. The serp-features API returns PAA count only, not question text. `paa-questions.json` (keyword.questions) provides actual questions and is merged into faq-research when serp-features has none.

**Output:** `docs/content/blog/posts/{category}/{slug}/data/faq-research.json`

**SISTRIX Credits:** ~1 credit per keyword (PAA questions endpoint)

### Step 3: Generate FAQ Questions

**Script:** `v2/scripts/blog/generate-faq-questions.php`

```bash
php v2/scripts/blog/generate-faq-questions.php --post=slug --category=category
```

**What it does:**

- Combines PAA questions, GSC queries, and keywords
- Generates standard questions based on topic
- Prioritizes questions by search volume and user intent
- Selects top 15 questions

**Output:** `docs/content/blog/posts/{category}/{slug}/data/faq-questions.json`

### Step 4: Write FAQ Answers

**Requirements:**

- **Length:** 40-80 words per answer
- **Structure:** Direct answer → Context → Actionable info
- **Tone:** Du tone (informal German)
- **Keywords:** Natural integration
- **Internal Links:** 2-3 per post total, contextual
- **Ordio Mentions:** Natural, not forced

**Template:**

```
[Direct answer in first sentence (10-15 words)]
[Context/details in middle sentences (20-40 words)]
[Actionable information or next steps (10-15 words)]
```

**Reference:** `docs/content/blog/FAQ_BEST_PRACTICES.md`

### Step 5: Implement FAQs in Post JSON

**Format:** FAQs are stored in the `faqs` array, NOT in HTML content:

```json
{
  "faqs": [
    {
      "question": "Question text?",
      "answer": "<p>Answer text with HTML formatting (40-80 words)...</p>"
    }
  ]
}
```

**Location:** Update the `faqs` array in the post JSON file.

**File:** `v2/data/blog/posts/{category}/{slug}.json`

**Important:** FAQs are rendered separately by the `BlogFAQ.php` component. Do NOT add FAQs to `content.html`.

### Step 6: Validate Implementation

**Check FAQs Array:**

```bash
php -r "\$data = json_decode(file_get_contents('v2/data/blog/posts/ratgeber/zeiterfassung-app.json'), true); echo 'FAQs found: ' . count(\$data['faqs'] ?? []) . \"\n\";"
```

**Add FAQs to Post:**

```bash
php v2/scripts/blog/add-faqs-to-post.php --post=slug --category=category --faqs=faqs.json
```

**Validate Schema:**

```bash
php v2/scripts/blog/validate-faq-schema.php --post=slug --category=category
```

## Workflow 2: Optimizing Existing FAQs

### Step 1: Audit Current Quality

**Script:** `v2/scripts/blog/audit-faq-quality.php`

```bash
php v2/scripts/blog/audit-faq-quality.php
```

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

**What it checks:**

- FAQ count (target: 10-15)
- Answer length (target: 40-80 words)
- Keyword integration
- Internal links
- Redundant questions

### Step 2: Collect Research Data for Optimization

**For posts needing improvement:**

```bash
php v2/scripts/blog/collect-faq-research-data.php --post=slug --category=category
```

**Compare existing FAQs with:**

- People Also Ask questions
- Top GSC queries
- Related keywords

### Step 3: Identify Improvements

**Based on audit findings:**

1. **Low FAQ count (< 10):** Add missing high-volume questions
2. **Short answers (< 40 words):** Expand with context and details
3. **Long answers (> 80 words):** Condense to optimal length
4. **Missing keywords:** Integrate primary keyword naturally
5. **Missing internal links:** Add 2-3 contextual links
6. **Redundant questions:** Remove or merge duplicates

### Step 4: Implement Improvements

**Update post JSON file** with improved FAQs in the `faqs` array (not in HTML content). Use the same format as Workflow 1, Step 5.

### Step 5: Validate Improvements

**Re-run quality audit:**

```bash
php v2/scripts/blog/audit-faq-quality.php
```

**Validate schema:**

```bash
php v2/scripts/blog/validate-faq-schema.php --post=slug --category=category
```

## Workflow 4: Preventing Duplicate FAQs

### Step 1: Check Existing FAQs Before Adding

**CRITICAL:** Always check for existing FAQs before adding new ones.

**Check existing FAQs:**

```bash
php -r "\$data = json_decode(file_get_contents('v2/data/blog/posts/{category}/{slug}.json'), true); echo 'Existing FAQs: ' . count(\$data['faqs'] ?? []) . \"\n\";"
```

**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
- Prevents duplicate questions
- Merges with existing FAQs instead of appending

### Step 2: Deduplication Process

**Run deduplication script periodically:**

```bash
php v2/scripts/blog/deduplicate-faqs.php --all --backup
```

**What it does:**

- Removes duplicate FAQ sections (keeps first occurrence)
- Merges multiple FAQ wrappers into single wrapper
- Removes duplicate questions (exact and fuzzy matching)
- Removes boilerplate/repetitive answer endings

### Step 3: Quality Checks Before Publishing

**Run validation:**

```bash
php v2/scripts/blog/validate-faq-schema.php --all
```

**Check for:**

- Duplicate questions (exact and fuzzy)
- Multiple FAQ wrappers (should be 1)
- FAQ count (optimal: 10-15)
- Answer length (40-80 words)
- Boilerplate text

**See:** `docs/content/blog/FAQ_MAINTENANCE_GUIDE.md` for complete maintenance procedures

## Workflow 3: Maintenance Schedule

### Quarterly Review

**Schedule:** Every 3 months

**Tasks:**

1. Run quality audit: `audit-faq-quality.php`
2. Review quality audit report
3. Collect fresh research data for top 20 posts
4. Update FAQs based on new PAA questions
5. Validate all changes

### Monthly Monitoring

**Tasks:**

1. Check GSC for new high-volume queries
2. Monitor Featured Snippet appearances
3. Track PAA question changes
4. Review FAQ performance metrics

### After New Post Publication

**Tasks:**

1. Add FAQs within 1 week of publication
2. Follow Workflow 1 (Creating FAQs for New Posts)
3. Validate implementation

## SISTRIX Credit Management

### Credit Limits

- **Daily Limit:** 2,000 credits
- **Weekly Limit:** 10,000 credits
- **Reset:** Daily at midnight, weekly on Monday

### Credit Usage Tracking

**Check current usage:**

```bash
cat v2/data/blog/sistrix-credits-log.json
```

**Credit costs:**

- `keyword.seo.serpfeatures` (PAA questions): 1 credit/keyword
- `keyword.seo.metrics` (keyword volume): 5 credits/keyword
- `keyword.seo.searchintent` (search intent): 1 credit/keyword

### Best Practices

1. **Use cache:** Research data is cached for 7 days
2. **Batch processing:** Process multiple posts in one run
3. **Prioritize:** Focus on high-value posts first
4. **Skip if cached:** Use `--skip-sistrix` flag to use cached data only

**Example:**

```bash
# Collect data for all posts (uses cache when available)
php v2/scripts/blog/collect-faq-research-data.php --all --skip-sistrix
```

## Quality Standards

### FAQ Count

- **Target:** 10-15 FAQs per post
- **Minimum:** 10 FAQs
- **Maximum:** 20 FAQs

### Answer Length

- **Target:** 40-80 words per answer
- **Minimum:** 40 words
- **Maximum:** 80 words

### Keyword Integration

- **Natural:** Keywords appear naturally, not forced
- **Primary keyword:** Should appear in at least 3-5 FAQs
- **No stuffing:** Avoid keyword repetition

### Internal Links

- **Frequency:** 2-3 links total across all FAQs
- **Relevance:** Links must be contextually relevant
- **Anchor text:** Natural, descriptive phrases

## Validation Checklist

### Before Publishing FAQs

- [ ] 10-15 FAQs per post
- [ ] Answers are 40-80 words each
- [ ] Natural keyword integration
- [ ] Du tone consistency
- [ ] 2-3 natural internal links
- [ ] Schema validates with Google Rich Results Test
- [ ] No duplicate questions
- [ ] FAQ extraction works correctly
- [ ] FAQ display works on blog post page

## Troubleshooting

### FAQs Not Displaying

**Check:**

1. FAQs are in the `faqs` array (not in HTML content)
2. FAQ structure is correct: `{"question": "...", "answer": "..."}`
3. Answers contain valid HTML formatting
4. Post JSON file is valid

**Test:**

```bash
php -r "\$data = json_decode(file_get_contents('v2/data/blog/posts/ratgeber/zeiterfassung-app.json'), true); print_r(\$data['faqs'] ?? []);"
```

### Schema Validation Fails

**Check:**

1. All FAQs included in schema
2. Answers match HTML exactly (word-for-word)
3. No HTML links in schema answers
4. Valid JSON syntax

**Test:**

```bash
php v2/scripts/blog/validate-faq-schema.php --post=slug --category=category
```

### SISTRIX API Errors

**Check:**

1. API key is valid
2. Credit limits not exceeded
3. Rate limiting (1 second delay between requests)
4. Cache available (use `--skip-sistrix` if needed)

## Related Documentation

- `docs/content/blog/FAQ_BEST_PRACTICES.md` - Best practices guide
- `docs/content/blog/FAQ_OPTIMIZATION_GUIDE.md` - Optimization guide
- `docs/content/blog/FAQ_IMPLEMENTATION.md` - Implementation details
- `.cursor/rules/blog-faq-optimization.mdc` - Cursor rules