OpenWriterControle/.opencode/context/content-creation/formats/written-content.md

<!-- Context: content-creation/written-content | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->

# Written Content Guidelines

Best practices for creating effective written content across formats: articles, blog posts, social media, newsletters, and long-form content.

---

## Article Structure

### Standard Article Flow

**1. Hook (First 50 words)**
- Grab attention immediately
- Promise clear value
- Create curiosity

**2. Problem/Context (100-200 words)**
- Establish the problem or topic
- Show why it matters
- Build relevance

**3. Main Content (Body)**
- Deliver on the promise
- Use clear structure (subheadings, lists)
- Include examples and data

**4. Conclusion (50-100 words)**
- Summarize key points
- Reinforce main takeaway
- Clear call-to-action

---

## Blog Post Best Practices

### Formatting for Readability

**Short paragraphs**:
- 1-3 sentences max
- White space improves scanning
- Mobile-friendly

**Subheadings every 200-300 words**:
- Break up long sections
- Enable skimming
- Improve SEO

**Bullet points and lists**:
- Easy to scan
- Highlight key points
- Increase engagement

**Bold key phrases**:
- Draw attention to important points
- Help skimmers find value
- Don't overuse (2-3 per section max)

---

### Blog Post Length Guidelines

**Short-form (300-600 words)**:
- Quick tips
- News and updates
- Opinion pieces
- Social media-friendly

**Medium-form (800-1500 words)**:
- How-to guides
- List posts
- Case studies
- Most versatile length

**Long-form (2000+ words)**:
- Comprehensive guides
- In-depth tutorials
- Research-backed content
- SEO pillar content

---

### Blog Post Templates

**How-To Post**:
1. Hook with the problem
2. Why this solution works
3. Step-by-step instructions
4. Common mistakes to avoid
5. Next steps

**List Post**:
1. Hook with promise (X ways to Y)
2. Brief intro
3. Each item with explanation
4. Summary of key points
5. Call-to-action

**Case Study**:
1. Hook with result
2. Starting situation
3. Challenge/problem
4. Solution/process
5. Results and lessons
6. How to apply it

---

## Social Media Posts

### Platform-Specific Guidelines

**Twitter/X**:
- Hook in first line
- Use line breaks for readability
- Thread for longer content
- End with engagement question or CTA

**LinkedIn**:
- Professional but personal tone
- Story-driven content performs well
- Use "see more" strategically
- Include relevant hashtags (3-5)

**Instagram**:
- Visual-first, caption supports
- Hook before "more" cutoff
- Use emojis strategically
- Hashtags in comments or end of caption

**Facebook**:
- Conversational tone
- Questions drive engagement
- Native video outperforms links
- Community-focused content

---

### Social Post Structure

**Pattern 1: Hook + Story + Lesson**
```
[Attention-grabbing first line]

[Short story or example]

[Key lesson or takeaway]

[Call-to-action or question]
```

**Pattern 2: Problem + Agitation + Solution**
```
[Identify relatable problem]

[Make it worse / show impact]

[Offer solution or insight]

[Next step]
```

**Pattern 3: List Format**
```
[Hook: X things about Y]

1. [Point with brief explanation]
2. [Point with brief explanation]
3. [Point with brief explanation]

[Closing thought or CTA]
```

---

## Newsletter Structure

### Email Newsletter Best Practices

**Subject Line**:
- 40-50 characters ideal
- Create curiosity or promise value
- Personalization when relevant
- A/B test regularly

**Preview Text**:
- First 50-100 characters matter
- Extend the subject line hook
- Don't waste with "View in browser"

**Opening**:
- Personal greeting
- Quick context or story
- Promise what's in this email

**Body**:
- One main idea per email (or clear sections)
- Scannable format
- Links to full content if needed
- Visual breaks (images, dividers)

**Closing**:
- Clear call-to-action
- Personal sign-off
- P.S. for secondary CTA or bonus

---

### Newsletter Types

**Curated Newsletter**:
- Intro with theme
- 3-7 curated items
- Brief commentary on each
- Why it matters

**Story Newsletter**:
- Personal story or case study
- Lesson or insight
- How to apply it
- Single clear CTA

**Educational Newsletter**:
- One main teaching point
- Step-by-step or framework
- Examples
- Action item

---

## Long-Form Content

### Long-Form Structure

**Comprehensive Guide Structure**:
1. Table of contents
2. Introduction (why this matters)
3. Main sections (3-7 major topics)
4. Examples and case studies
5. Common mistakes/FAQs
6. Conclusion and next steps
7. Resources and further reading

---

### Long-Form Best Practices

**Navigation**:
- Table of contents with jump links
- Progress indicators
- "Back to top" links
- Clear section breaks

**Engagement**:
- Vary content types (text, images, examples)
- Include interactive elements
- Break up with quotes or callouts
- Summarize key points in boxes

**Retention**:
- Deliver value early and often
- Use open loops (promise info later)
- Include surprising insights
- Make it skimmable

---

## SEO Considerations

### On-Page SEO Basics

**Title Tag**:
- Include target keyword
- 50-60 characters
- Compelling and clickable

**Meta Description**:
- 150-160 characters
- Include keyword naturally
- Promise clear value

**Headings**:
- H1 for main title (one per page)
- H2 for main sections
- H3 for subsections
- Include keywords naturally

**Internal Links**:
- Link to related content
- Use descriptive anchor text
- Help readers find more value

**Images**:
- Descriptive file names
- Alt text for accessibility and SEO
- Compressed for speed

---

### Keyword Integration

**Natural placement**:
- Title and first paragraph
- Subheadings where relevant
- Throughout body naturally
- Don't force or over-optimize

**Semantic keywords**:
- Related terms and phrases
- Answer related questions
- Cover topic comprehensively

---

## Readability Optimization

### Readability Checklist

- [ ] Grade level: 8th grade or below for general audience
- [ ] Sentence length: Average 15-20 words
- [ ] Paragraph length: 3 sentences or less
- [ ] Active voice: 80%+ of sentences
- [ ] Transition words: Connect ideas smoothly
- [ ] Jargon: Explained or avoided
- [ ] Examples: Concrete and relatable

---

### Readability Tools

**Hemingway Editor**:
- Highlights complex sentences
- Identifies passive voice
- Suggests simpler alternatives

**Grammarly**:
- Grammar and spelling
- Tone detection
- Clarity suggestions

**Yoast SEO** (WordPress):
- Readability analysis
- SEO optimization
- Content structure

---

## Content Quality Checklist

Before publishing, verify:

- [ ] Hook grabs attention in first 50 words
- [ ] Clear value proposition
- [ ] Scannable format (headings, lists, bold)
- [ ] Short paragraphs (1-3 sentences)
- [ ] Examples and specifics (not just theory)
- [ ] Clear call-to-action
- [ ] Proofread for errors
- [ ] Links work and are relevant
- [ ] Images optimized and have alt text
- [ ] Mobile-friendly formatting

---

## Common Written Content Mistakes

### ❌ Burying the Lead
Starting with background instead of value.

### ✅ Lead with Value
Put the most important information first.

---

### ❌ Walls of Text
Long paragraphs that are hard to read.

### ✅ White Space
Short paragraphs with visual breaks.

---

### ❌ Vague Promises
"This will help you improve your content."

### ✅ Specific Value
"Learn the 3-second hook formula that increased my engagement 300%."

---

### ❌ No Clear CTA
Ending without telling readers what to do next.

### ✅ Clear Next Step
"Try this framework on your next post and let me know how it works."

---

## Usage

Apply these guidelines when creating:
- Blog posts and articles
- Social media content
- Email newsletters
- Landing page copy
- Long-form guides
- Any written content

**Remember**: Write for humans first, optimize for algorithms second. Clarity and value always win.