# Content Flow Prevention Guide

**Last Updated:** 2026-01-15

## Purpose

This guide provides prevention measures, content creation checklists, and review processes to prevent content flow issues in new blog posts.

## Prevention Measures

### 1. Content Structure Template

**Use this structure for all new posts:**

```markdown
# [Title]

[Introduction paragraph - 2-3 sentences]
- Hook
- Context
- What the post covers

## [Core Definition Heading]

[Definition paragraph - clear, comprehensive]
- What is [topic]?
- Why does it matter?
- Key characteristics

## [Main Content Sections]

[Explanation, examples, advanced topics]

## Conclusion

[Summary, next steps]
```

### 2. Definition Placement Rule

**CRITICAL:** Always place the core definition within the first 20% of content.

**Before writing:**
1. Identify the core concept/topic
2. Write the definition first
3. Place it immediately after the introduction
4. Then write explanations, examples, advanced topics

**Definition patterns:**
- `Definition: [term]`
- `Was ist [term]?`
- `Was sind [term]?`
- `Was bedeutet [term]?`

### 3. FAQ Management

**CRITICAL:** FAQs must NEVER be in `content.html`.

**Process:**
1. Write FAQs separately
2. Add to `faqs` array in JSON file
3. Never add FAQ sections to `content.html`
4. FAQs render automatically via `BlogFAQ.php` component

**FAQ quality:**
- 10-15 questions optimal
- Answers: 40-80 words
- Complement content (don't duplicate)
- Include primary keyword naturally

### 4. Logical Flow Checklist

**Before finalizing content:**

- [ ] Introduction hooks reader
- [ ] Core definition appears early (within first 20%)
- [ ] Content progresses: Simple → Complex
- [ ] Examples follow definitions
- [ ] Advanced topics come after basics
- [ ] Smooth transitions between sections
- [ ] Conclusion summarizes key points

## Content Creation Checklist

### Phase 1: Planning

- [ ] Core topic identified
- [ ] Primary keyword selected
- [ ] Target audience defined
- [ ] Content structure planned
- [ ] Definition written first

### Phase 2: Writing

- [ ] Introduction written (hook + context)
- [ ] Core definition placed early (within first 20%)
- [ ] Content flows logically
- [ ] Examples support definitions
- [ ] Advanced topics follow basics
- [ ] Conclusion summarizes

### Phase 3: FAQ Creation

- [ ] FAQs written separately
- [ ] FAQs added to `faqs` array only
- [ ] No FAQ sections in `content.html`
- [ ] FAQ count: 10-15 questions
- [ ] FAQ answers: 40-80 words

### Phase 4: Review

- [ ] Content flow validated
- [ ] Definition placement checked
- [ ] FAQ separation verified
- [ ] Heading hierarchy correct
- [ ] Non-text elements preserved

## Review Process for New Posts

### Step 1: Automated Validation

**Run validation script:**

```bash
php v2/scripts/blog/validate-content-flow.php --post=slug --category=category --exit-on-error
```

**Checks:**
- Definition placement
- FAQ separation
- Heading hierarchy
- Content flow score

**Target:** No issues, flow score ≥80/100

### Step 2: Manual Review

**Content flow:**
- [ ] Read content aloud for natural flow
- [ ] Verify definitions appear before examples
- [ ] Check logical progression
- [ ] Ensure smooth transitions

**Definition placement:**
- [ ] Core definition within first 20%
- [ ] Definition is clear and comprehensive
- [ ] Definition uses natural language

**FAQ separation:**
- [ ] No FAQ headings in `content.html`
- [ ] FAQs exist only in `faqs` array
- [ ] FAQ count optimal (10-15)

### Step 3: Visual Inspection

**Browser testing:**
- [ ] Content flows visually
- [ ] Definitions appear early
- [ ] FAQs render correctly
- [ ] Non-text elements work
- [ ] Mobile responsive

## Common Mistakes to Avoid

### ❌ Mistake 1: Definition After Examples

**Wrong:**
```
Intro
Examples of [topic]
What is [topic]? ← Too late!
```

**Correct:**
```
Intro
What is [topic]? ← Early!
Examples of [topic]
```

### ❌ Mistake 2: FAQs in Content HTML

**Wrong:**
```html
<h2>Häufige Fragen</h2>
<p>Question 1...</p>
```

**Correct:**
```json
{
  "faqs": [
    {
      "question": "Question 1",
      "answer": "Answer 1"
    }
  ]
}
```

### ❌ Mistake 3: Illogical Content Order

**Wrong:**
```
Intro
Advanced topic discussion
Basic definition ← Too late!
```

**Correct:**
```
Intro
Basic definition ← Early!
Advanced topic discussion
```

## Pre-Commit Validation

**Add to git hooks:**

```bash
#!/bin/bash
# .git/hooks/pre-commit

php v2/scripts/blog/validate-content-flow.php --post=$POST_SLUG --category=$CATEGORY --exit-on-error

if [ $? -ne 0 ]; then
    echo "Content flow validation failed. Fix issues before committing."
    exit 1
fi
```

## Integration with Content Workflow

**See:** `docs/content/CONTENT_CREATION_WORKFLOW_2026.md`

**Phase 4.1: Content Flow Review**
- Run validation script
- Check definition placement
- Verify FAQ separation
- Review logical flow

## Tools & Resources

### Validation Tools

- `v2/scripts/blog/analyze-content-flow.php` - Detailed analysis
- `v2/scripts/blog/validate-content-flow.php` - Pre-commit validation
- `v2/scripts/blog/remove-faqs-from-content.php` - FAQ removal

### Documentation

- `docs/content/blog/CONTENT_FLOW_GUIDELINES.md` - Complete guidelines
- `.cursor/rules/blog-content-flow.mdc` - Cursor rules
- `docs/content/blog/TIER1_CONTENT_FLOW_REVIEW_SUMMARY.md` - Review summary

## Best Practices Summary

1. **Write definition first** - Before examples or advanced topics
2. **Place definition early** - Within first 20% of content
3. **Separate FAQs** - Never in `content.html`, only in `faqs` array
4. **Logical progression** - Simple → Complex, General → Specific
5. **Validate before commit** - Run validation script
6. **Review manually** - Read content aloud, check flow
7. **Test visually** - Browser test, verify rendering

## Related Documentation

- `docs/content/blog/CONTENT_FLOW_GUIDELINES.md` - Complete guidelines
- `.cursor/rules/blog-content-flow.mdc` - Cursor rules
- `docs/content/CONTENT_CREATION_WORKFLOW_2026.md` - Content workflow