# FAQ rework decision tree

**Last Updated:** 2026-04-04

Short runbook for **rebuilding or improving an existing FAQ set** (any surface). Use with the hub: [FAQ_WEBSITE_STANDARD.md](FAQ_WEBSITE_STANDARD.md).

## 1. Inventory

- Export current questions and answers (blog: `faqs` in post JSON; product: `v2/scripts/product-pages/extract-product-faqs.php`; tools/templates: from page PHP or pipeline JSON).
- Note count, order, and any subsection structure.

## 2. Data coverage

- Load or refresh **GSC** queries for the URL (or parent pattern).
- Load **PAA** / related questions (SISTRIX exports, Serper, or `collect-faq-research-data.php` on blog).
- Mark each high-impression or high-intent query as **covered**, **weak**, or **missing**.

## 3. Overlap with page body

- Blog: `php v2/scripts/blog/check-h2-faq-overlap.php --post=SLUG --category=CAT`
- Templates: `check-template-block-faq-overlap.php` before merge/add.
- Tools/product: manually compare FAQ questions to on-page H2s and hero blocks.

**Decision:** If overlap is high → **remove** FAQ, **merge** into body, or **rephrase** to a distinct micro-intent (e.g. edge case not explained above the fold).

## 4. Prune

- Drop **off-topic** or **pattern-violation** questions (blog: `detect-faq-patterns.php`, `validate-faq-topic-relevance.php`).
- Merge **near-duplicates** (semantic similarity); keep the stronger answer.
- **Prune before add** to avoid FAQ bloat.

## 5. Reorder

- Apply logical flow: definitions → how-to → requirements → when/why → comparisons → edge cases.
- Within each band, prioritize **higher-volume / higher-click** queries from GSC when known.

## 6. Add

- Add questions only for **documented gaps** (step 2), phrased as **natural German questions**, not raw keyword dumps.
- Respect surface **count** targets (see hub matrix).

## 7. Answer format

- Default **paragraphs**; use **`<ul>` / `<ol>`** only when the question demands enumeration (see hub).
- Stay in **40–80 words** where that surface standard applies; tools/legal may need slightly longer answers with editorial sign-off.

## 8. Ordio and links

- Ordio mentions **only** when contextually useful; internal links **opportunity-driven** (lexikon/tool/product), not in every answer.

## 9. Validate

- **Schema / parity:** blog `validate-faq-schema.php`; templates `validate-template-faq-schema.php`; product steps in [PRODUCT_PAGE_FAQ_GUIDE.md](pages/product-pages/PRODUCT_PAGE_FAQ_GUIDE.md); tools Rich Results Test + parity check vs visible HTML.
- **Quality:** blog `validate-faq-quality.php`; template/product quality scripts as documented.

## 10. Measure (later)

- After 4–8 weeks, re-export the same GSC slice; compare clicks, impressions, and average position for FAQ-aligned queries.
- Do **not** treat loss of FAQ **rich-result** UI in Google as a failure (see hub).

## Full FAQ refresh (existing hub post, copy-paste chain)

Use after refreshing improvement data ([IMPROVEMENT_DATA_COLLECTION_GUIDE.md](blog/IMPROVEMENT_DATA_COLLECTION_GUIDE.md)). Replace `SLUG`, `CAT`, and the path to `faq-answers-optimized.json` with the post folder under `docs/content/blog/posts/CAT/SLUG/data/`.

```bash
# Data (minimum; or run-post-improvement-pipeline.php for one shot)
php v2/scripts/blog/collect-post-performance-gsc.php --post=SLUG --category=CAT
php v2/scripts/blog/collect-post-performance-ga4.php --post=SLUG --category=CAT
php v2/scripts/blog/collect-post-keywords-sistrix.php --post=SLUG --category=CAT
php v2/scripts/blog/collect-faq-research-data.php --post=SLUG --category=CAT

# Inventory + overlap gate
php v2/scripts/blog/check-h2-faq-overlap.php --post=SLUG --category=CAT

# Apply pipeline answers (preserve order when curated: --no-sort)
php v2/scripts/blog/add-faqs-to-post.php --post=SLUG --category=CAT \
  --faqs=docs/content/blog/posts/CAT/SLUG/data/faq-answers-optimized.json --replace --no-sort

# Validate
php v2/scripts/blog/validate-faq-quality.php --post=SLUG --category=CAT
php v2/scripts/blog/validate-faq-schema.php --post=SLUG --category=CAT
php v2/scripts/blog/validate-faq-topic-relevance.php --post=SLUG --category=CAT
php v2/scripts/blog/audit-faq-source-drift.php --post=SLUG --category=CAT
make blog-post-validate-faq POST=SLUG CAT=CAT
```

Source-of-truth note: [FAQ_SOURCE_OF_TRUTH.md](blog/FAQ_SOURCE_OF_TRUTH.md).

## Quick reference: blog scripts

| Goal | Script |
|------|--------|
| Full analysis | `comprehensive-faq-analysis.php` |
| Uniqueness | `check-faq-uniqueness.php` |
| Reorder | `reorder-faqs-by-logical-flow.php --write` |
| Add from JSON | `add-faqs-to-post.php` |