---
name: developer-advocacy
description: When the user wants to do developer advocacy activities including conference talks, live coding, podcasts, and building in public. Trigger phrases include "developer advocacy," "devrel," "conference talk," "CFP," "call for papers," "live coding," "podcast," "building in public,"...
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/developer-advocacy
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Developer Advocacy
## When to Use

Use this skill when you need when the user wants to do developer advocacy activities including conference talks, live coding, podcasts, and building in public. Trigger phrases include "developer advocacy," "devrel," "conference talk," "CFP," "call for papers," "live coding," "podcast," "building in public,"...

This skill helps you with developer advocacy activities: conference talks, live coding demos, podcast appearances, and building in public. Covers talk proposals, demo prep, social presence, and measuring impact.

---

## Before You Start

**Load your audience context first.** Read `.agents/developer-audience-context.md` to understand:

- Who you're trying to reach (conferences they attend, podcasts they listen to)
- What topics resonate (pain points, interests)
- Your product's positioning (what story to tell)
- Voice & tone (how formal/technical to be)

If the context file doesn't exist, run the `developer-audience-context` skill first.

---

## Conference Talks

### Finding the Right Conferences

| Conference Type | Best For | Examples |
|-----------------|----------|----------|
| **Large industry** | Brand awareness, reach | KubeCon, AWS re:Invent, React Summit |
| **Regional** | Local community, accessible | Local meetups, city tech conferences |
| **Niche** | Targeted audience, expertise | GraphQL Conf, RustConf |
| **Company-hosted** | Ecosystem presence | Vercel Ship, GitHub Universe |
| **Unconferences** | Community connection | BarCamps, DevOpsDays |

### Talk Proposal (CFP) Framework

**The winning formula:**
```
Specific Problem + Unique Angle + Clear Takeaways = Accepted Talk
```

**CFP Template:**

```markdown
# Title
[Action verb] + [specific outcome] + [with/using what]
Example: "Building Real-Time Features with Edge Functions and WebSockets"

# Abstract (100-200 words)
[Hook: Problem or curiosity gap]
[What you'll cover]
[What attendees will learn/be able to do]

# Description (detailed, for reviewers)
[Problem context]
[Why this approach]
[Talk structure]
[Your credibility to give this talk]

# Outline
- [Time] Introduction / Problem statement
- [Time] Section 1
- [Time] Section 2
- [Time] Section 3
- [Time] Live demo / walkthrough
- [Time] Key takeaways / Q&A

# Audience
[Who this is for]
[Prerequisite knowledge]
[What they'll learn]

# Bio
[Your relevant experience]
[Why you're qualified]
```

### Title Patterns That Work

| Pattern | Example |
|---------|---------|
| **How I X** | "How I Reduced Deploy Time by 80%" |
| **X in Y Minutes** | "Kubernetes Security in 15 Minutes" |
| **The X of Y** | "The Psychology of Error Messages" |
| **Beyond X** | "Beyond Console.log: Modern Debugging" |
| **X for Y** | "GraphQL for REST Developers" |
| **Lessons from X** | "Lessons from 1000 Production Outages" |

### Talk Types

| Type | Length | Best For |
|------|--------|----------|
| **Lightning** | 5-10 min | Single concept, quick demo |
| **Standard** | 25-45 min | Technical deep-dive |
| **Keynote** | 45-60 min | Big picture, inspiring |
| **Workshop** | 2-4 hours | Hands-on learning |
| **Panel** | 30-60 min | Discussion, multiple perspectives |

### Talk Prep Checklist

| Phase | Tasks |
|-------|-------|
| **2 months before** | Outline, start slides, test demos |
| **1 month before** | Draft complete, first practice run |
| **2 weeks before** | Slides polished, demos solid, practice 3x |
| **1 week before** | Record yourself, get feedback, finalize |
| **Day before** | Test all tech, backup slides, rest |
| **Day of** | Arrive early, test A/V, hydrate |

---

## Live Coding & Demos

### The Demo Danger Zone

| Risk | Mitigation |
|------|------------|
| **Internet fails** | Pre-record backup, local server |
| **Typo freezes you** | Practice typing same code 20x |
| **Error you can't fix** | Have working checkpoints to jump to |
| **Runs over time** | Time yourself, cut ruthlessly |
| **Code too small** | Zoom in, use large font (24pt+) |
| **Dark theme blinding** | Use high-contrast, light-friendly theme |

### Demo Prep Framework

**The 10-3-1 Rule:**
- Run your demo **10 times** in practice
- Have **3 checkpoints** you can jump to if stuck
- **1 backup** (video recording of it working)

**Pre-demo checklist:**
- [ ] Close unnecessary apps
- [ ] Clear browser history/tabs
- [ ] Notifications OFF (Slack, email, calendar)
- [ ] Font size: 24pt+ for terminal, 20pt+ for editor
- [ ] Git stash/branch for clean starting point
- [ ] Environment variables ready
- [ ] Test on the actual projector/screen if possible

### Live Coding Tips

| Tip | Why |
|-----|-----|
| **Type slowly** | Audience needs to follow |
| **Narrate what you type** | "I'm creating a new handler..." |
| **Explain errors** | "This error means X, let me fix it" |
| **Use snippets** | For boilerplate, not core concepts |
| **Show the result** | Always run the code, show output |
| **Checkpoint commits** | `git checkout checkpoint-1` |

---

## Podcast Guesting

### Finding Podcasts

| Approach | How |
|----------|-----|
| **Direct search** | "top [your tech] podcasts" |
| **Guest networks** | Podmatch, Matchmaker.fm |
| **Peer asks** | "What podcasts do you listen to?" |
| **Twitter search** | "[topic] podcast episode" |
| **Listen Notes** | Podcast search engine |

### Pitch Template

```
Subject: Guest Idea: [Specific Topic] for [Podcast Name]

Hi [Host Name],

I've been listening to [Podcast] for [time] — loved your episode on [specific episode].

I'd love to come on and talk about [specific topic]. Here's the angle:

[2-3 sentences on what you'd discuss and why it matters to their audience]

A bit about me:
- [Relevant credential 1]
- [Relevant credential 2]
- [Link to past podcast/talk]

Would this be a fit?

[Your name]
```

### Pre-Podcast Prep

| Prep Item | Details |
|-----------|---------|
| **Research the show** | Listen to 2-3 episodes, understand format |
| **Research the host** | Their interests, style, Twitter |
| **Prep talking points** | 3-5 main things you want to say |
| **Prep stories** | Specific examples, not generalities |
| **Audio setup** | Good mic, quiet room, headphones |
| **Water nearby** | You'll be talking a lot |

### During the Podcast

| Do | Don't |
|----|-------|
| Tell stories with specifics | Give generic advice |
| Pause before answering | Um and ah nervously |
| Disagree respectfully | Always agree to be polite |
| Promote subtly | Hard sell your product |
| Be concise | Ramble without structure |
| Show enthusiasm | Be monotone |

### Post-Podcast

| Action | Timing |
|--------|--------|
| Thank the host | Same day |
| Share when published | Immediately |
| Engage with comments | First week |
| Cross-promote | Your newsletter, blog |
| Stay in touch | Ongoing relationship |

---

## Building in Public

### What to Share

| Category | Content Ideas |
|----------|---------------|
| **Progress** | "Shipped X today, here's what I learned" |
| **Challenges** | "Stuck on X, tried Y and Z, here's what worked" |
| **Decisions** | "Why we chose X over Y" |
| **Metrics** | Revenue, users, growth (transparently) |
| **Behind scenes** | Team, process, tools |
| **Learnings** | "Mistake we made and how we fixed it" |

### Build in Public Formats

| Format | Platform | Cadence |
|--------|----------|---------|
| **Tweet thread** | Twitter/X | Daily-weekly |
| **Changelog** | Blog, Notion, website | Weekly |
| **Indie hacker posts** | Indie Hackers, HN | Monthly |
| **Video update** | YouTube, Loom | Weekly-monthly |
| **Newsletter** | Email | Weekly |
| **Livestream** | Twitch, YouTube | Weekly |

### What NOT to Share

| Avoid | Why |
|-------|-----|
| **Customer data** | Privacy, trust |
| **Team conflicts** | Professionalism |
| **Security details** | Vulnerability |
| **Competitor attacks** | Looks petty |
| **Venting** | Not productive |

---

## Social Presence (Twitter/X)

### Developer Twitter Playbook

| Content Type | % of Posts | Example |
|--------------|------------|---------|
| **Value content** | 60% | Tips, tutorials, insights |
| **Engagement** | 20% | Replies, retweets with commentary |
| **Personal** | 10% | Behind-the-scenes, personality |
| **Promotion** | 10% | Your product, talks, content |

### Tweet Formats That Work

| Format | Example |
|--------|---------|
| **Thread** | "10 things I learned building X" |
| **Hot take** | "Unpopular opinion: [opinion]" |
| **Quick tip** | "TIL: You can do X by..." |
| **Question** | "What's your favorite way to..." |
| **Meme/humor** | Tech jokes, relatable content |
| **Showcase** | "Just shipped X, here's how it works" |
| **Appreciation** | "Shoutout to @person for..." |

### Engagement Strategy

| Action | Frequency |
|--------|-----------|
| Tweet original content | Daily |
| Reply to others | 5-10x daily |
| Quote tweet with value | 2-3x weekly |
| DM interesting people | Weekly |
| Join Twitter Spaces | As relevant |

### Growing Your Presence

| Tactic | Implementation |
|--------|----------------|
| **Consistency** | Post daily, engage daily |
| **Niche down** | Be known for ONE thing first |
| **Reply game** | Add value to big accounts' tweets |
| **Collaborate** | Twitter Spaces, threads together |
| **Cross-promote** | Newsletter, talks, blog |

---

## Measuring Impact

### Advocacy Metrics

| Activity | Metrics |
|----------|---------|
| **Talks** | Attendees, feedback scores, recording views |
| **Content** | Views, shares, engagement |
| **Social** | Followers, engagement rate, reach |
| **Podcasts** | Listener estimates, traffic spikes |
| **Community** | Growth, engagement, sentiment |

### Attribution Challenges

Developer advocacy impact is notoriously hard to measure. Proxy metrics:

| Signal | What It Indicates |
|--------|-------------------|
| **Traffic spikes** | Content/talk/podcast drove visits |
| **"How did you hear about us?"** | Direct attribution |
| **Social mentions** | Brand awareness |
| **Inbound leads quality** | Community-qualified leads |
| **Conference invites** | Growing reputation |

### Reporting Framework

Monthly advocacy report:

```markdown
# Developer Advocacy Report - [Month]

## Talks & Appearances
- [Talk 1]: [Conference], [Attendees], [Link]
- [Podcast 1]: [Show], [Episode link]

## Content Published
- [Article 1]: [Views], [Engagement]
- [Video 1]: [Views]

## Social Growth
- Twitter: +X followers, Y impressions
- Notable tweets: [Links]

## Community
- Discord/Slack: +X members, Y messages
- Notable threads/discussions

## Learnings
- What worked: [X]
- What didn't: [Y]
- Trying next: [Z]
```

---

## Advocacy Career Path

### Role Levels

| Level | Focus |
|-------|-------|
| **Junior DA** | Content creation, community support, talk prep |
| **Developer Advocate** | Talks, own content strategy, community building |
| **Senior DA** | Strategy, mentoring, major conferences |
| **Staff DA** | Cross-company impact, industry thought leadership |
| **Head of DevRel** | Team building, strategy, executive alignment |

### Skill Development

| Skill | How to Develop |
|-------|----------------|
| **Public speaking** | Meetups, Toastmasters, practice |
| **Writing** | Blog consistently, get feedback |
| **Video** | YouTube, live streaming, improve iteratively |
| **Technical depth** | Build projects, contribute to OSS |
| **Community** | Moderate, organize events, connect people |

---

## Tools

| Tool | Use Case |
|------|----------|
| **[Octolens](https://octolens.com)** | Monitor your name/brand across GitHub, Twitter, Reddit, HN, Stack Overflow. Track conference mentions. Find podcast opportunities. Measure share of voice. |
| **Cal.com / Calendly** | Schedule podcast appearances |
| **StreamYard** | Live streaming setup |
| **Descript** | Video/podcast editing |
| **Canva / Figma** | Slides and graphics |
| **Otter.ai** | Transcription for talks |
| **Notion** | Talk prep, content calendar |
| **Buffer / Typefully** | Social scheduling |

---

## Related Skills

- `developer-audience-context` — Know who you're reaching
- `devrel-content` — Written content strategy
- `community-building` — Community management
- `open-source-marketing` — OSS-specific advocacy
- `hacker-news-strategy` — HN engagement

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: developer-audience-context
description: When the user wants to establish or update their developer audience context. Also use when starting any other developer marketing skill to ensure foundational context is loaded. Trigger phrases include "developer persona," "target developers," "who are our developers," "developer...
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/developer-audience-context
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Developer Audience Context
## When to Use

Use this skill when you need when the user wants to establish or update their developer audience context. Also use when starting any other developer marketing skill to ensure foundational context is loaded. Trigger phrases include "developer persona," "target developers," "who are our developers," "developer...

This skill helps you create and maintain `.agents/developer-audience-context.md` — a foundational document that captures everything about your target developers. All other developer marketing skills reference this document first, so you only define your audience once.

---

## Before You Start

Check if `.agents/developer-audience-context.md` exists:

- **If it exists**: Read it and offer to update specific sections
- **If it doesn't exist**: Create the directory and file, then walk through each section

---

## Two Ways to Build Context

### Option 1: Auto-Draft from Codebase (Recommended)

Analyze existing materials to draft an initial version:

1. **README.md** — Product description, features, getting started
2. **Documentation** — `/docs`, API reference, tutorials
3. **Landing pages** — `index.html`, marketing copy
4. **package.json / pyproject.toml** — Dependencies reveal ecosystem
5. **GitHub Issues** — Common questions, frustrations, use cases
6. **Existing blog posts** — Technical content, tutorials

After drafting, walk through each section to validate and fill gaps.

### Option 2: Start from Scratch

Ask questions section-by-section. Don't advance until the current section is complete.

---

## The 10 Sections to Capture

### 1. Product Overview

| Field | What to capture |
|-------|-----------------|
| Product name | Official name and any aliases |
| One-liner | "We help [developers] do [X] without [Y]" |
| Category | API, SDK, CLI, SaaS, open source library, infrastructure |
| Core technology | Languages, frameworks, platforms supported |
| Pricing model | Free/open source, freemium, usage-based, seat-based |

### 2. Developer Persona

Not "developers" generically — get specific:

| Field | What to capture |
|-------|-----------------|
| Primary role | Backend, frontend, full-stack, DevOps, data, ML, mobile |
| Seniority | Junior, mid, senior, staff, lead, architect |
| Company size | Solo, startup, scale-up, enterprise |
| Industry verticals | Fintech, healthtech, e-commerce, gaming, B2B SaaS |
| Tech stack | Languages, frameworks, cloud providers they use |
| Decision authority | Individual contributor, team lead, buyer, influencer |

**Ask**: "Describe the developer who gets the most value from your product in one paragraph. What's their day-to-day like?"

### 3. Where They Hang Out

Developers research before they buy. Know where:

| Channel | Specifics to capture |
|---------|---------------------|
| Communities | Specific subreddits, Discord servers, Slack groups |
| Social | Twitter/X hashtags, LinkedIn groups |
| Content | Blogs they read, newsletters they subscribe to, podcasts |
| Events | Conferences, meetups, hackathons |
| Code | GitHub topics, Stack Overflow tags |

**Pro tip**: Use social listening tools to monitor conversations across Hacker News, Reddit, Stack Overflow, GitHub, and Twitter. See where discussions about your problem space happen organically.

### 4. Problems & Pain Points

Capture the actual problems, not your solution's features:

| Level | What to capture |
|-------|-----------------|
| Functional | "I can't do X" / "X takes too long" / "X is error-prone" |
| Emotional | Frustration, anxiety, embarrassment, fear |
| Situational | When does the pain occur? What triggers the search? |

**Ask**: "What's the #1 frustration that brings developers to you?"

**Research**: Search Reddit, Hacker News, and Stack Overflow for complaints about your problem space. Capture verbatim quotes.

### 5. Current Alternatives

What are developers using today instead of you?

| Alternative type | Examples |
|-----------------|----------|
| Direct competitors | Tools that solve the same problem |
| DIY / build it yourself | Custom scripts, internal tools |
| Indirect solutions | Workarounds, manual processes |
| Do nothing | Live with the pain |

For each alternative, capture:
- Why developers choose it
- What's frustrating about it
- What would make them switch

### 6. Key Differentiators

What makes you different — in developer terms:

| Differentiator type | Example |
|--------------------|---------|
| Technical | "10x faster," "No dependencies," "Type-safe" |
| DX (Developer Experience) | "5-minute setup," "Great docs," "First-class CLI" |
| Ecosystem | "Works with X," "Built for Y framework" |
| Philosophy | "Open source," "Privacy-first," "Local-first" |

**Warning**: Avoid marketing fluff. Developers see through "best-in-class" and "enterprise-grade." Use specific, provable claims.

### 7. Verbatim Developer Language

Capture exact phrases developers use — not polished marketing copy:

| Category | Examples |
|----------|----------|
| Describing the problem | "This is such a pain," "I wish I could just..." |
| Describing your product | How they explain it to others |
| Objections | "But what about...", "I'm worried that..." |
| Praise | Testimonials, tweets, GitHub comments |

**Sources**: GitHub issues, Twitter mentions, Hacker News comments, support tickets, sales calls, community Slack/Discord.

### 8. Technical Trust Signals

What proof points matter to developers:

| Signal type | Examples |
|-------------|----------|
| Adoption | GitHub stars, npm downloads, Docker pulls |
| Quality | Test coverage, security audits, uptime SLA |
| Community | Contributors, Discord members, forum activity |
| Credibility | Backed by X, used by Y, created by Z |
| Transparency | Open source, public roadmap, changelog |

### 9. Conversion Actions

What does success look like at each stage?

| Stage | Primary action | Secondary actions |
|-------|---------------|-------------------|
| Awareness | Star repo, follow on Twitter | Read blog post, share content |
| Consideration | Clone repo, read docs | Watch demo, join Discord |
| Trial | Sign up, install SDK | Complete quickstart, make first API call |
| Activation | Reach "Hello World" moment | Integrate into real project |
| Conversion | Upgrade to paid | Add team members, expand usage |

### 10. Voice & Tone

How should you sound when talking to these developers?

| Dimension | Spectrum |
|-----------|----------|
| Formality | Casual ← → Professional |
| Technicality | Accessible ← → Deep technical |
| Personality | Neutral ← → Opinionated |
| Humor | Serious ← → Playful |

**Examples**:
- Stripe → Professional, precise, clean
- Vercel → Modern, confident, developer-first
- Supabase → Friendly, accessible, community-driven
- Tailwind → Opinionated, direct, practical

---

## Output Format

Save to `.agents/developer-audience-context.md` with this structure:

```markdown
# Developer Audience Context

Last updated: [DATE]

## Product Overview
[Section content]

## Developer Persona
[Section content]

## Where They Hang Out
[Section content]

## Problems & Pain Points
[Section content]

## Current Alternatives
[Section content]

## Key Differentiators
[Section content]

## Verbatim Developer Language
[Section content]

## Technical Trust Signals
[Section content]

## Conversion Actions
[Section content]

## Voice & Tone
[Section content]
```

---

## Maintenance

Update this document when:

- You learn something new from user research
- You find great verbatim quotes
- Your positioning or differentiation changes
- You expand to new developer segments

---

## Tools

| Tool | Use case |
|------|----------|
| **[Octolens](https://octolens.com)** | Monitor developer conversations across GitHub, Hacker News, Reddit, Stack Overflow, Twitter. Essential for capturing verbatim language, finding pain points, and understanding where your developers hang out. |
| **GitHub Search** | Find how developers describe problems in issues |
| **Twitter Advanced Search** | Find discussions about your space |
| **Google Alerts** | Track mentions of competitors and problem keywords |

---

## Related Skills

After establishing context, these skills will reference it:

- `devrel-content` — Writing content that resonates
- `hacker-news-strategy` — Engaging on HN authentically
- `developer-onboarding` — Optimizing time-to-value
- `developer-seo` — Targeting the right technical queries
- `competitor-tracking` — Understanding your competitive landscape

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: developer-churn
description: When the user wants to understand, reduce, or recover from developer churn. Trigger phrases include "why developers leave," "churn rate," "win-back campaign," "at-risk users," "developer retention," "preventing churn," or "competitor switching."
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/developer-churn
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Developer Churn
## When to Use

Use this skill when you need when the user wants to understand, reduce, or recover from developer churn. Trigger phrases include "why developers leave," "churn rate," "win-back campaign," "at-risk users," "developer retention," "preventing churn," or "competitor switching.".

This skill helps you understand why developers leave, identify at-risk users before they churn, and win back those who've already left. No guilt trips or desperate discounts — just honest understanding and genuine value.

---

## Before You Start

1. **Load your developer audience context**:
   - Check if `.agents/developer-audience-context.md` exists
   - If not, run the `developer-audience-context` skill first
   - Understanding your developers' alternatives and pain points is critical for churn analysis

2. **Gather your data**:
   - Current churn rate by segment
   - Most recent churned users (last 30-90 days)
   - Support ticket history for churned users
   - Usage patterns before churn
   - Exit survey data (if any)

---

## Understanding Developer Churn

Developer churn is different from typical SaaS churn:

| Consumer/SMB SaaS | Developer Tools |
|-------------------|-----------------|
| Price sensitivity high | Value sensitivity high |
| Features drive decisions | DX drives decisions |
| Support tickets = engagement | Support tickets = friction |
| Monthly churn cycles | Project-based churn |
| Competitor marketing works | Peer recommendations work |

**Key insight**: Developers don't leave because of price. They leave because of friction, frustration, or finding something better.

---

## The 6 Reasons Developers Churn

### 1. Developer Experience (DX) Issues

**Symptoms**:
- High time-to-first-value
- Frequent support tickets on basic tasks
- Complaints about docs or SDKs
- "It's too complicated" feedback

**Root causes**:
- Poor documentation
- Buggy SDKs
- Breaking changes without migration paths
- Confusing authentication
- Missing quickstarts

**Detection signals**:
```
- Support tickets mentioning "confused" or "doesn't work"
- High signup-to-activation drop-off
- Long time between signup and first API call
- Multiple failed API calls before success
```

### 2. Pricing and Billing Friction

**Symptoms**:
- Downgrades before cancellation
- Usage dropping to stay under limits
- Questions about billing
- Requests for enterprise/custom pricing

**Root causes**:
- Unpredictable costs
- Expensive for early-stage
- No free tier or too restrictive
- Poor price-to-value perception
- Billing surprises

**Detection signals**:
```
- Sudden usage reduction after billing cycle
- Pricing page visits from logged-in users
- Support tickets about unexpected charges
- API calls stopping mid-month
```

### 3. Superior Alternatives

**Symptoms**:
- Sudden churn (not gradual)
- Multiple team members churning together
- Churning without complaints
- "We're going a different direction"

**Root causes**:
- Competitor launched better feature
- Open source alternative matured
- Bigger player entered your space
- Their stack changed (new language/framework)

**Detection signals**:
```
- Sudden stop in usage (no gradual decline)
- Competitor mentions in support/feedback
- Traffic to your docs from competitor domains
- Social mentions comparing you to alternatives
```

### 4. Project Death

**Symptoms**:
- Gradual decline to zero
- No support contact
- Ignores all communication
- Whole company churn

**Root causes**:
- Their project was cancelled
- Startup failed
- Prototype never went to production
- Budget cuts

**Reality check**: You can't prevent this. Don't waste energy trying.

**Detection signals**:
```
- Slow decline over weeks/months
- No login activity
- No response to any outreach
- Domain no longer resolves
```

### 5. Integration Failure

**Symptoms**:
- High engagement then sudden stop
- Technical support tickets unresolved
- "Doesn't work with X" feedback
- Stuck at implementation phase

**Root causes**:
- Your product doesn't fit their stack
- Missing integration they need
- Technical limitation they hit
- SDK doesn't support their use case

**Detection signals**:
```
- Lots of docs page views on specific integration
- Support tickets about specific tech stack
- API calls from testing environment only
- "Evaluation" mentioned in communications
```

### 6. Involuntary Churn

**Symptoms**:
- Churn after failed payment
- No other warning signs
- Often surprised when contacted

**Root causes**:
- Expired credit card
- Card fraud protection
- Changed payment method
- Forgot to update billing

**Detection signals**:
```
- Failed payment events
- Usage continues until hard cutoff
- Quick reactivation when contacted
```

---

## Identifying At-Risk Developers

### Engagement Scoring

Create a simple health score:

| Signal | Weight | Calculation |
|--------|--------|-------------|
| API calls | 30% | This week vs last 4 week avg |
| Login frequency | 20% | Days since last login |
| Feature adoption | 20% | % of core features used |
| Support sentiment | 15% | Positive/negative ticket ratio |
| Billing health | 15% | Payment success, plan changes |

**Health score thresholds**:
- **80-100**: Healthy - continue nurturing
- **60-79**: Watch - proactive outreach
- **40-59**: At-risk - intervention needed
- **0-39**: Critical - personal contact

### Early Warning Signs

Monitor for these patterns:

**Usage-based signals**:
```
- API calls dropped >50% week-over-week
- No login in 14+ days
- Stopped using new features
- API errors increasing
- Only using deprecated endpoints
```

**Support-based signals**:
```
- Multiple tickets on same issue
- Negative sentiment in tickets
- Questions about data export
- Asking about contract/cancellation
- Unusual silence from previously engaged user
```

**Billing-based signals**:
```
- Viewing pricing page while logged in
- Downgrading plan
- Removing team members
- Asking about prorating cancellation
```

### Building an Alert System

Set up automated alerts:

```
ALERT: At-risk developer detected

User: [EMAIL/COMPANY]
Health score: 42 (was 78 last week)

Triggers:
- API calls down 73% this week
- 2 unresolved support tickets (both negative sentiment)
- Viewed pricing page 3 times

Recommended action: Personal outreach from [OWNER]
```

---

## Churn Interviews and Feedback

### The Right Approach

**Do**:
- Ask genuinely curious questions
- Accept their decision gracefully
- Make it about learning, not winning them back
- Keep it short (5 questions max)
- Offer something valuable for their time

**Don't**:
- Try to sell during the interview
- Get defensive about feedback
- Promise things to change their mind
- Make them feel guilty
- Take longer than 10 minutes

### Exit Survey (Email)

```
Subject: Quick question about your [PRODUCT] experience

Hey [NAME],

I noticed you've stopped using [PRODUCT]. No worries — these things happen.

If you have 30 seconds, I'd genuinely love to know:

What's the #1 reason you stopped?

[ ] Found a better alternative
[ ] Too expensive
[ ] Too complicated to use
[ ] Missing feature I needed
[ ] Project ended / no longer needed
[ ] Other: _____

Your feedback directly shapes our roadmap.

Thanks for giving us a try.

— [NAME], [TITLE] at [COMPANY]
```

### Exit Interview Questions

If they agree to a call (offer a $50 gift card or donation to their choice):

1. **Opening**: "Thanks for chatting. I'm not here to win you back — just want to understand your experience."

2. **Journey**: "Walk me through your experience with [PRODUCT], from signup to today."

3. **Breaking point**: "Was there a specific moment when you decided to stop using us?"

4. **Alternative**: "What are you using now instead? What made that a better fit?"

5. **Hypothetical**: "If you could wave a magic wand and change one thing about [PRODUCT], what would it be?"

6. **Close**: "Anything else you want us to know?"

### Analyzing Feedback

Track churn reasons by category:

| Category | % of Churn | Actionable? | Priority |
|----------|------------|-------------|----------|
| DX issues | 35% | Yes | High |
| Pricing | 25% | Yes | Medium |
| Alternatives | 20% | Partially | Medium |
| Project death | 15% | No | None |
| Integration gaps | 5% | Yes | Low |

Focus energy on actionable categories with high impact.

---

## Win-Back Campaigns

### When to Win Back

**Good candidates**:
- Churned due to fixable issues (you've since fixed)
- Left for alternative that's now inferior
- Project death but new project starting
- Billing/involuntary churn

**Bad candidates**:
- Left with strong negative sentiment
- Fundamental product mismatch
- Company no longer exists
- Recently churned (wait at least 30 days)

### Win-Back Sequence

**Timing**: Start 30-60 days after churn. Not sooner.

**Email 1: What's new (Day 30)**

```
Subject: [PRODUCT] update: [SPECIFIC THING THEY CARED ABOUT]

Hey [NAME],

I know you moved on from [PRODUCT] a while back. Totally respect that.

Quick update: We [SPECIFIC IMPROVEMENT RELEVANT TO THEIR CHURN REASON].

[1-2 sentence details with link to changelog/announcement]

If your situation has changed, we'd be happy to have you back.
If not, no worries — hope you're building great things.

— [NAME]
```

**Email 2: Social proof (Day 45)**

```
Subject: How [COMPANY SIMILAR TO THEIRS] uses [PRODUCT] now

Hey [NAME],

Thought you might find this interesting — [SIMILAR COMPANY]
just shared how they're using [PRODUCT] to [RELEVANT USE CASE].

[Link to case study or technical post]

Might spark some ideas for your current project.

— [NAME]
```

**Email 3: Direct offer (Day 60)**

```
Subject: Would 30 days free help?

Hey [NAME],

Last note from me.

If you've been thinking about giving [PRODUCT] another shot,
I can set you up with 30 days free on whatever plan you need.

Just reply and I'll make it happen.

If not, I'll stop emailing. Thanks for reading this far.

— [NAME]
```

### Win-Back Offers

Appropriate offers for developers:

| Offer | When to Use |
|-------|-------------|
| Extended free tier | Price-sensitive churners |
| Free upgrade for 30 days | Feature-gap churners |
| 1:1 technical help | DX-issue churners |
| Early access to new feature | Competitor-switch churners |
| Nothing (just information) | Project-death churners |

**What NOT to offer**:
- Permanent discounts (sets bad precedent)
- Desperate "please come back" messaging
- Anything to project-death churners

---

## Monitoring Competitor Switches

### Social Listening Setup

Set up monitoring for:

1. **Direct mentions**:
   - "[Your product] vs [Competitor]"
   - "Switching from [Your product] to [Competitor]"
   - "Migrating away from [Your product]"

2. **Problem space discussions**:
   - Monitor conversations in your category
   - See what alternatives people recommend
   - Track sentiment about your product vs others

3. **Competitor momentum**:
   - Track competitor mentions and sentiment
   - New features they're launching
   - Developer reactions to their updates

### Competitive Intelligence Workflow

```
Weekly review:

1. Check social listening tools for:
   - Any mentions of switching from you
   - Competitor launches or announcements
   - Developer complaints about your category

2. Analyze patterns:
   - Are switches going to one competitor?
   - What features/issues drive switches?
   - What's competitor doing that resonates?

3. Update churn prevention:
   - Add new at-risk signals
   - Prioritize features that prevent switches
   - Address common complaints
```

---

## Reducing Involuntary Churn

Involuntary churn (payment failures) is often 20-40% of total churn. Fix it.

### Prevention

| Strategy | Implementation |
|----------|----------------|
| Card expiration warnings | Email 30 and 7 days before |
| Multiple payment methods | Allow card + PayPal + ACH |
| Annual billing incentives | 2 months free for annual |
| Dunning emails | 3-4 emails over 14 days |
| Grace period | 7-14 days before hard cutoff |
| In-app warnings | Banner when payment method needs update |

### Dunning Sequence

**Email 1: Immediate**

```
Subject: Payment failed — update your card

Hey [NAME],

We couldn't process your payment for [PRODUCT].

Update your card: [LINK]

Your account is still active. We'll retry in 3 days.

— [PRODUCT]
```

**Email 2: Day 3**

```
Subject: Second attempt failed — action needed

Hey [NAME],

Still can't process your payment. Your service will be
interrupted on [DATE] if we can't charge a valid card.

Update now: [LINK]

Having trouble? Reply and we'll help.

— [PRODUCT]
```

**Email 3: Day 7**

```
Subject: Your [PRODUCT] account will be paused in 3 days

Hey [NAME],

Final notice: Your account will be paused on [DATE].

This means:
- API keys will stop working
- Webhooks will be disabled
- Your data stays safe (we keep it for 90 days)

Update your payment: [LINK]

— [PRODUCT]
```

**Email 4: Day 10**

```
Subject: Your account has been paused

Hey [NAME],

Your [PRODUCT] account is now paused due to payment failure.

To reactivate:
1. Update your payment method: [LINK]
2. Your service will resume immediately

Your data is safe and will be kept for 90 days.

Questions? Reply to this email.

— [PRODUCT]
```

### Recovery Tactics

| Tactic | Impact |
|--------|--------|
| Smart retries | Retry 3-5 times over 2 weeks at different times |
| Card updater services | Automatically update expired cards |
| Alternative payment request | "Try a different card?" |
| Payment link in dunning | Direct link, not "log in to update" |
| Phone/SMS for enterprise | High-value accounts get personal contact |

---

## Churn Metrics Dashboard

### Key Metrics

| Metric | How to Calculate | Target |
|--------|------------------|--------|
| Monthly churn rate | Churned users / Starting users | <5% |
| Net revenue churn | Lost revenue - expansion / Starting MRR | <2% |
| Time to churn | Avg days from signup to churn | Increasing |
| Win-back rate | Returned users / Churned users | >5% |
| Involuntary churn % | Payment churn / Total churn | <20% |

### Cohort Analysis

Track retention by:
- **Signup month**: Are recent cohorts retaining better?
- **Acquisition source**: Which channels produce sticky users?
- **Plan type**: Do paid users retain better than free?
- **Activation status**: Do activated users retain better?

### Health Score Tracking

```
Weekly health score distribution:

Healthy (80-100): 65% of users
Watch (60-79):    20% of users
At-risk (40-59):  10% of users
Critical (0-39):   5% of users

Trend: At-risk increased 3% this week (investigate)
```

---

## Common Mistakes

| Mistake | Why It Fails | Fix |
|---------|--------------|-----|
| Ignoring project death | Wasting resources on unwinnable users | Accept it and focus on actionable churn |
| Offering discounts first | Trains users to threaten churn for discounts | Lead with value, not price |
| Win-back too soon | Feels desperate, annoys recently churned | Wait 30+ days |
| Not listening to feedback | Repeating the same mistakes | Actually fix what they complained about |
| Generic win-back campaigns | Irrelevant messages get ignored | Personalize based on churn reason |
| Blaming developers | "They just didn't get it" | Your DX is the problem |

---

## Tools

| Tool | Use Case |
|------|----------|
| **[Octolens](https://octolens.com)** | Monitor competitor switches, track developer sentiment, detect early warning signs from social mentions |
| **Segment** | Track usage events for health scoring |
| **Amplitude/Mixpanel** | Cohort analysis and retention tracking |
| **Customer.io** | Automated at-risk and win-back sequences |
| **Stripe** | Dunning management for involuntary churn |
| **Profitwell Retain** | Specialized churn reduction for payments |

---

## Related Skills

- `developer-audience-context` — Understand alternatives and pain points
- `developer-email-sequences` — Re-engagement and win-back emails
- `competitor-tracking` — Monitor competitive landscape
- `developer-listening` — Capture feedback before churn
- `developer-onboarding` — Prevent churn at the source

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: developer-listening
description: "Monitor what developers say about your brand, competitors, and the problems they're solving. Track mentions and conversations across GitHub, Hacker News, Reddit, Stack Overflow, Twitter, and Discord. Trigger phrases: \"developer listening\", \"monitor developer conversations\", \"track..."
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/developer-listening
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Developer Listening
## When to Use

Use this skill when you need monitor what developers say about your brand, competitors, and the problems they're solving. Track mentions and conversations across GitHub, Hacker News, Reddit, Stack Overflow, Twitter, and Discord. Trigger phrases: "developer listening", "monitor developer conversations", "track...

Monitor developer conversations across platforms to understand sentiment, find engagement opportunities, and gather competitive intelligence.

## Overview

Developer listening is the practice of systematically monitoring what developers say about your brand, competitors, and the problems your product solves. Unlike traditional social listening, developer listening requires monitoring technical platforms where developers actually spend time: GitHub, Hacker News, Reddit programming communities, Stack Overflow, Twitter/X, and Discord servers.

Effective developer listening helps you:
- Understand how developers perceive your product
- Find frustrated users who need help (and might churn)
- Discover engagement opportunities before competitors
- Gather unfiltered product feedback
- Track competitive positioning in real conversations
- Identify content gaps and documentation issues

## Setting Up Your Monitoring Strategy

### 1. Define Your Keyword Categories

Before setting up monitoring, organize keywords into categories:

**Brand Keywords:**
- Your product name and common misspellings
- Your company name
- Key team members' names (for attribution)
- Your GitHub org/repos
- Your Twitter handles

**Competitor Keywords:**
- Direct competitor names
- Competitor product features
- Competitor pricing/plan names

**Problem Keywords:**
- Pain points your product solves
- Error messages you help with
- Workflow descriptions ("deploy to kubernetes", "manage API keys")
- "How do I..." phrases relevant to your space

**Buy Intent Keywords:**
- "[category] recommendation"
- "best [tool type] for [use case]"
- "looking for [solution]"
- "alternative to [competitor]"
- "[competitor] vs"

### 2. Set Up Monitoring Tools

Choose a social listening tool that aggregates mentions across developer platforms (GitHub, Hacker News, Reddit, Stack Overflow, Twitter).

**Recommended Keyword Structure:**
- Create separate keywords for brand, competitors, and problem spaces
- Use exact match for brand names to reduce noise
- Use broader matching for problem keywords
- Set up negative keywords to filter irrelevant mentions

### 3. Platform-Specific Monitoring

**GitHub:**
- Monitor issues mentioning your product in other repos
- Track discussions in relevant GitHub Discussions
- Watch for your product in awesome-lists and comparison repos
- Monitor stars/forks of competitor repos for traction signals

**Hacker News:**
- High-signal but low-volume
- Comments often contain detailed technical feedback
- "Show HN" and "Ask HN" posts reveal developer needs
- Threads about competitors are engagement opportunities

**Reddit:**
- r/programming, r/webdev, r/devops, r/selfhosted, etc.
- Subreddit-specific cultures require tailored responses
- Question threads are high-intent opportunities

**Stack Overflow:**
- Monitor tags related to your product category
- Questions reveal documentation gaps
- Answers from competitors show their positioning

**Twitter/X:**
- Real-time sentiment and virality
- Developer influencer conversations
- Conference and event discussions
- Complaint threads often go viral

**Discord:**
- Harder to monitor but high-signal
- Join relevant community servers manually
- Look for integration opportunities with popular servers

## Sentiment Analysis and Prioritization

### Prioritization Framework

Not all mentions deserve equal attention. Prioritize based on:

**High Priority (Respond within hours):**
- Negative sentiment from existing users
- Direct questions about your product
- Complaints going viral
- Competitor comparisons where you're losing
- Buy-intent signals from ideal customer profiles

**Medium Priority (Respond within 24-48 hours):**
- Neutral mentions seeking recommendations
- Feature requests in public forums
- Documentation confusion
- Competitor criticism (potential switchers)

**Low Priority (Monitor and aggregate):**
- General industry discussions
- Competitor praise (learn from it)
- Historical mentions for trend analysis

### Sentiment Filtering

Most monitoring tools offer sentiment filtering. Key queries to set up:

- Negative sentiment mentions from the last 30 days
- High-relevance mentions that haven't been engaged with yet
- Platform-specific filters (Hacker News, Reddit, Twitter)

## Finding Engagement Opportunities

### Types of Engagement Opportunities

**Frustrated Users:**
- Complaining about your product = urgent support opportunity
- Complaining about competitors = potential conversion
- Complaining about the problem space = thought leadership opportunity

**Questions and Recommendations:**
- Direct questions about your product
- "What tool should I use for X" threads
- Comparison requests

**Buy Intent Signals:**
- "Looking for a [your category]"
- "Evaluating [competitor] vs [competitor]"
- "Need to migrate from [competitor]"
- "Budget approved for [solution]"

### Engagement Best Practices

1. **Be helpful first, promotional second** - Answer the question before mentioning your product
2. **Disclose affiliation** - "I work at [company]" builds trust
3. **Match the platform culture** - HN hates marketing speak, Reddit values authenticity
4. **Provide value even if they don't convert** - Good advice builds reputation
5. **Don't argue with critics** - Acknowledge, fix if valid, move on

## Competitive Intelligence from Conversations

### What to Track

**Competitor Mentions:**
- Praise (what are they doing right?)
- Criticism (opportunities for you)
- Feature requests (what's missing?)
- Churn signals ("migrating away from")

**Positioning Shifts:**
- How competitors describe themselves
- Which use cases they emphasize
- Pricing and packaging discussions

**Community Sentiment:**
- Overall vibe toward competitors
- Developer trust levels
- Support quality perception

### Extracting Insights

Track trends over time using your monitoring tool's analytics:

- Sentiment trends for competitors over 90 days
- Mention volume comparison between your brand and top competitors
- Platform breakdown (where are conversations happening?)

## Tools

### Social Listening

Use a monitoring tool that tracks developer platforms. Key capabilities to look for:
- Multi-platform coverage (GitHub, HN, Reddit, Stack Overflow, Twitter)
- Sentiment analysis
- Keyword alerts and filtering
- Analytics and trend tracking

### Platform-Specific Tools

**GitHub Search:**
- Use `gh search issues` and `gh search repos` for GitHub-specific monitoring
- Track issues mentioning your product in other repositories

**Twitter/X Search:**
- Advanced search operators for precise monitoring
- Track specific accounts and hashtags
- Tools like Typefully, TweetDeck, or Hootsuite for monitoring

**Reddit:**
- Native Reddit search with subreddit filters
- Third-party tools like Syften or F5Bot for alerts

## Related Skills

- **competitor-tracking** - Systematic competitor analysis beyond conversation monitoring
- **alternatives-pages** - Convert competitive insights into comparison content
- **community-engagement** - Best practices for responding to developer conversations

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: developer-newsletter
description: When the user wants to create, write, or improve a newsletter for developer audiences. Trigger phrases include "newsletter," "email marketing," "developer email," "weekly digest," "dev newsletter," "email subscribers," "newsletter growth," or "email list."
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/developer-newsletter
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Developer Newsletter
## When to Use

Use this skill when you need when the user wants to create, write, or improve a newsletter for developer audiences. Trigger phrases include "newsletter," "email marketing," "developer email," "weekly digest," "dev newsletter," "email subscribers," "newsletter growth," or "email list.".

This skill helps you build and write newsletters that developers actually open, read, and look forward to receiving. Covers content strategy, writing, growth, and deliverability.

---

## Before You Start

**Load your audience context first.** Read `.agents/developer-audience-context.md` to understand:

- Who you're writing for (role, seniority, tech stack)
- What content resonates (problems, interests)
- Where else they consume content (to avoid duplicate effort)
- Voice & tone (how casual/technical)

If the context file doesn't exist, run the `developer-audience-context` skill first.

---

## Newsletter Strategy

### Define Your Newsletter Type

| Type | Description | Example |
|------|-------------|---------|
| **Product updates** | Changelog, new features, tips | Vercel's updates |
| **Curated links** | Best content from around the web | TLDR, Bytes |
| **Original content** | Your own articles, tutorials | Cassidy Williams |
| **Community digest** | What happened in your community | Dev community roundups |
| **Educational series** | Teaching a topic over time | Course-style newsletters |

**Best practice**: Pick ONE primary type. You can mix in others, but have a clear identity.

### Frequency Matrix

| Frequency | Best For | Risk |
|-----------|----------|------|
| **Daily** | Curated links, news | Fatigue, hard to maintain |
| **Weekly** | Most newsletters | Sweet spot for most |
| **Bi-weekly** | Original content heavy | Can lose momentum |
| **Monthly** | Product updates, digests | Easy to forget you exist |

**Developer preference**: Weekly is the sweet spot. Developers are busy and inbox-protective.

---

## Content Mix Framework

### The 70-20-10 Rule

| Percentage | Content Type | Purpose |
|------------|--------------|---------|
| **70%** | Value content | Teach, inform, help |
| **20%** | Product content | Updates, features, how-tos |
| **10%** | Promotional | CTAs, asks, sales |

### Content Categories

Build a rotation of these:

| Category | Examples |
|----------|----------|
| **Tutorials** | "How to implement X" |
| **News analysis** | "What Y announcement means for you" |
| **Tool/library roundups** | "5 libraries for handling Z" |
| **Code snippets** | "Quick tip: better error handling" |
| **Community highlights** | "Best from our Discord this week" |
| **Industry takes** | "Why I think X is overhyped" |
| **Behind the scenes** | "How we built feature Y" |
| **Q&A** | "You asked, we answered" |

---

## Writing Developer Emails

### Subject Line Framework

What works for developers:

| Pattern | Example | Why It Works |
|---------|---------|--------------|
| **Specific benefit** | "Cut your build time by 40%" | Concrete value |
| **Technical curiosity** | "The JavaScript feature nobody uses" | Triggers curiosity |
| **Direct announcement** | "v2.0 is here: async/await support" | Clear, newsworthy |
| **Number + topic** | "7 TypeScript tricks senior devs use" | Scannable, specific |
| **Question** | "Are you still using callbacks?" | Pattern interrupt |
| **Breaking news** | "React 19 is out: what you need to know" | Timely, urgent |

What doesn't work:

| Avoid | Why |
|-------|-----|
| ALL CAPS | Spam signals |
| "Quick question" | Manipulative |
| Excessive emoji | Looks like marketing |
| "You won't believe..." | Clickbait fatigue |
| No subject line | Just... no |

### Pre-header Text

The preview text after the subject line. Use it.

| Subject | Pre-header |
|---------|------------|
| "v2.0 is here" | "Plus: breaking changes to watch for" |
| "This week in Node.js" | "fetch() drama, npm security, and a cool CLI" |

### Email Structure

```
[Short personal intro - 1-2 sentences]

[Main content sections with clear headers]

[Code snippet if relevant]

[Quick links section]

[Sign-off with personality]
```

### Code in Email

Code rendering is tricky in email. Options:

| Approach | Pros | Cons |
|----------|------|------|
| **Inline code** (`backticks`) | Works everywhere | No highlighting |
| **Plain text block** | Reliable | Ugly |
| **Image of code** | Beautiful | Can't copy, accessibility issues |
| **"View in browser" link** | Full formatting | Friction |
| **Styled HTML tables** | Decent formatting | Complex, can break |

**Recommendation**: Keep code short. Use inline code for small snippets, link to full examples.

```html
<pre style="background-color: #1e1e1e; color: #d4d4d4; padding: 16px; border-radius: 4px; font-family: 'Fira Code', monospace; font-size: 14px; overflow-x: auto;">
const result = await fetch('/api/data');
</pre>
```

---

## Subject Line Testing

### A/B Test Framework

Test one variable at a time:

| Variable | Version A | Version B |
|----------|-----------|-----------|
| **Length** | "TypeScript 5.0 features" | "7 TypeScript 5.0 features that will change how you write code" |
| **Specificity** | "New features" | "Async imports, decorators, and 5 more" |
| **Format** | Statement | Question |
| **Personalization** | Generic | "[Name], your weekly digest" |
| **Emoji** | None | One relevant emoji |

### Subject Line Checklist

Before sending:

- [ ] Under 50 characters (mobile preview)
- [ ] No spam trigger words (free, act now, limited time)
- [ ] Specific, not vague
- [ ] Matches email content (no bait and switch)
- [ ] Would YOU open this?

---

## Growth Tactics

### Organic Growth

| Tactic | Implementation |
|--------|----------------|
| **Blog footer CTA** | "Get posts like this in your inbox" with inline form |
| **Content upgrades** | "Download the full checklist" for email |
| **Exit intent** | Popup when leaving (use sparingly) |
| **Twitter/social mentions** | "I write about this weekly in my newsletter" |
| **Documentation CTA** | Subscribe box in docs footer |
| **Open source README** | Newsletter link in project README |
| **Conference talks** | "Sign up for slides + bonus content" |

### Referral Programs

| Reward Tier | Reward Example |
|-------------|----------------|
| **1 referral** | Shoutout in newsletter |
| **5 referrals** | Exclusive content / early access |
| **10 referrals** | Swag (stickers, t-shirt) |
| **25 referrals** | 1:1 call / premium access |

### Cross-Promotion

Partner with complementary newsletters:

| Your Newsletter | Good Partners |
|-----------------|---------------|
| React-focused | TypeScript, Node.js, frontend newsletters |
| DevOps | Cloud, Kubernetes, infrastructure newsletters |
| AI/ML | Python, data science newsletters |

Swap mentions, not full ads.

---

## Avoiding Spam Filters

### Technical Setup

| Requirement | What to Do |
|-------------|------------|
| **SPF** | Add DNS record authorizing your sender |
| **DKIM** | Sign emails cryptographically |
| **DMARC** | Policy for handling auth failures |
| **Custom domain** | Send from `news@yourcompany.com`, not personal |
| **Warm up** | Start with small sends, increase gradually |

### Content Hygiene

| Do | Don't |
|-----|-------|
| Plain text version | HTML only |
| Reasonable image ratio | All images, no text |
| Clear unsubscribe | Hidden or difficult unsub |
| Consistent sending | Sporadic, unpredictable |
| Clean list | Bounces, inactive, purchased |

### Red Flag Words

Avoid in subject lines and body:

| Category | Words to Avoid |
|----------|----------------|
| **Urgency** | Act now, Limited time, Expires |
| **Free stuff** | Free, No cost, No obligation |
| **Money** | $$, Cash, Earn, Investment |
| **Exaggeration** | Amazing, Incredible, Best ever |
| **Spam classics** | Click here, Winner, Congratulations |

---

## Email Service Providers

### Developer-Friendly Options

| ESP | Best For | Dev Features |
|-----|----------|--------------|
| **Buttondown** | Simple, markdown-first | API, RSS import, minimal |
| **ConvertKit** | Creator newsletters | Automations, landing pages |
| **Mailchimp** | General purpose | Robust API, integrations |
| **Resend** | Developer-first | React Email, great DX |
| **Loops** | SaaS companies | Product-focused features |
| **Beehiiv** | Growth-focused | Referrals, monetization |

### DIY Options

| Tool | Use Case |
|------|----------|
| **Resend + React Email** | Custom transactional + marketing |
| **Postmark** | Reliability-focused |
| **SendGrid** | Scale-focused |

---

## Metrics & Benchmarks

### Key Metrics

| Metric | Developer Newsletter Benchmark |
|--------|-------------------------------|
| **Open rate** | 30-50% (higher than B2C) |
| **Click rate** | 5-15% |
| **Unsubscribe rate** | <0.5% per send |
| **Spam complaints** | <0.1% |
| **List growth rate** | 5-10% monthly |

### What to Track

| Metric | What It Tells You |
|--------|------------------|
| **Open rate by subject** | Subject line effectiveness |
| **Click rate by link** | Content resonance |
| **Reply rate** | Engagement depth |
| **Unsubscribe after send** | Content fit |
| **Forward rate** | Shareability |
| **Growth source** | Best acquisition channels |

---

## Newsletter Template

```markdown
Subject: [Specific, benefit-driven headline]
Pre-header: [Teaser that complements subject]

---

Hey [first name],

[1-2 sentence personal intro or hook]

## [Main Section 1]

[2-3 paragraphs with value]

\`\`\`javascript
// Quick code example if relevant
\`\`\`

## [Main Section 2]

[Content]

## Quick Links

- [Link 1]: One-line description
- [Link 2]: One-line description
- [Link 3]: One-line description

## From the Community

[Highlight something from Discord/Twitter/GitHub]

---

[Personal sign-off]

[Name]

P.S. [Optional: extra CTA, fun fact, or teaser]
```

---

## Tools

| Tool | Use Case |
|------|----------|
| **[Octolens](https://octolens.com)** | Monitor developer conversations for newsletter content ideas. Track what topics are trending on HN, Reddit, and Twitter. |
| **Buttondown/ConvertKit/Beehiiv** | Newsletter platforms |
| **SparkLoop** | Referral program management |
| **Mailmeteor/Email Octopus** | Budget-friendly sending |
| **Mail-Tester** | Check spam score before sending |
| **Litmus/Email on Acid** | Email rendering preview |

---

## Related Skills

- `developer-audience-context` — Know who you're writing for
- `devrel-content` — Source content for your newsletter
- `community-building` — Generate community content
- `developer-advocacy` — Build your personal brand alongside newsletter

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: developer-onboarding
description: 'Get developers to "Hello World" fast with optimized quickstarts, tutorials, and sample apps. Trigger phrases: developer onboarding, time to first value, quickstart guide, hello world tutorial, developer activation, onboarding checklist, sample apps, getting started experience, reduce...'
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/developer-onboarding
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Developer Onboarding
## When to Use

Use this skill when you need get developers to "Hello World" fast with optimized quickstarts, tutorials, and sample apps. Trigger phrases: developer onboarding, time to first value, quickstart guide, hello world tutorial, developer activation, onboarding checklist, sample apps, getting started experience, reduce...

Get developers from signup to working code as fast as possible, then guide them to deeper engagement.

## Overview

Developer onboarding is the critical window between "I signed up" and "I understand how to use this." You have about 10 minutes of developer attention. Every second of confusion, every error message without guidance, every "it should work but doesn't" moment costs you users.

Great onboarding feels like pair programming with someone who anticipated every question. Bad onboarding feels like being dropped in a foreign city without a map.

## Before You Start

Review the `/devmarketing-skills/skills/developer-audience-context` skill to understand your target developers. A hobbyist building side projects needs different onboarding than an enterprise architect evaluating tools for production. Review `/devmarketing-skills/skills/developer-signup-flow` to ensure signup flows smoothly into onboarding.

## Time-to-First-Value Optimization

### Defining "First Value"

First value isn't "made an API call." First value is when the developer sees your tool doing something useful for them.

| Tool Type | First Value Moment |
|-----------|-------------------|
| API | Response returns meaningful data |
| SDK | Library performs expected function |
| Database | Query returns results |
| Hosting | App is live and accessible |
| Auth | User successfully logs in |
| Payment | Test charge processes |

### Measuring Time to First Value (TTFV)

Track timestamps at each stage:

```
signup_completed: 2024-01-15T10:00:00Z
dashboard_loaded: 2024-01-15T10:00:05Z
api_key_copied: 2024-01-15T10:01:30Z
first_api_call: 2024-01-15T10:04:45Z
first_successful_response: 2024-01-15T10:04:46Z  # TTFV = 4:46
```

**Benchmarks by category:**
- Simple APIs: <5 minutes
- SDKs requiring installation: <10 minutes
- Complex infrastructure: <30 minutes
- Self-hosted: <60 minutes

### Removing TTFV Obstacles

Map every step and eliminate blockers:

**Common TTFV killers:**
1. Email verification before dashboard access
2. API keys hidden in account settings
3. Quickstart assumes dependencies already installed
4. First example requires paid features
5. Error messages without resolution guidance
6. Docs search finds outdated tutorials

**TTFV audit process:**
1. Create new account (fresh browser, no cookies)
2. Screen record your first 30 minutes
3. Note every moment of confusion or friction
4. Time each step
5. Repeat with 5 different developer personas

## Quickstart Checklist Design

### The Ideal Quickstart Structure

```markdown
# Quickstart: [Specific Goal] in 5 Minutes

What you'll build: [Screenshot or description of end result]

Prerequisites:
- Node.js 18+ (check: node --version)
- npm or yarn

## Step 1: Install the SDK
[One command, copy button]

## Step 2: Initialize with your API key
[Code with placeholder, copy button]

## Step 3: Make your first request
[Complete working example, copy button]

## Step 4: See the result
[Expected output shown]

## Next steps
- [Link to common second task]
- [Link to full documentation]
```

### Checklist Patterns That Work

**Progress indicators (Stripe style):**
```
Your integration progress:
[x] Create account
[x] Get API keys
[ ] Install SDK
[ ] Make first API call
[ ] Handle webhooks
```

**Contextual next steps (Vercel style):**
```
You've deployed your first site.

What's next?
[ ] Add a custom domain
[ ] Set up environment variables
[ ] Enable analytics
```

### Common Quickstart Failures

**Too much context upfront:**
```
# Bad: The history of authentication
Before we begin, let's understand OAuth 2.0...
[500 words of background]

# Good: Jump to action
Install the SDK and make your first authenticated request.
```

**Assuming environment:**
```
# Bad
Run `npm install` to install dependencies.

# Good
npm install our-sdk
# Or with yarn: yarn add our-sdk
# Or with pnpm: pnpm add our-sdk
```

**Hidden prerequisites:**
```
# Bad (prerequisite discovered in Step 3)
Step 3: Connect to Redis
First, make sure Redis is running...

# Good (prerequisites listed upfront)
Prerequisites:
- Redis 6+ running locally (docker run -p 6379:6379 redis)
```

## Interactive vs Static Tutorials

### When to Use Interactive Tutorials

**Interactive tutorials work for:**
- Complex setup sequences
- Concepts that benefit from immediate feedback
- Onboarding flows where you control the environment
- Features requiring API keys or credentials

**Interactive tutorial tools:**
- Embedded code editors (CodeSandbox, StackBlitz)
- Terminal emulators (Instruqt, Killercoda)
- In-dashboard walkthroughs (Appcues, Pendo)
- Interactive notebooks (Jupyter, Observable)

### When Static Documentation Wins

**Static docs work better for:**
- Reference documentation
- Copy-paste code snippets
- Steps involving local development
- Content that changes frequently

### Hybrid Approach

**Best practice: Offer both**

```
# Make Your First API Request

## Quick version (copy-paste)
[Code block with copy button]

## Interactive version
[Launch in StackBlitz] [Try in CodeSandbox]

## Video walkthrough
[5-minute embedded video]
```

### Interactive Tutorial UX Guidelines

**Do:**
- Save progress automatically
- Allow skipping ahead
- Show estimated time remaining
- Provide escape hatch to static docs
- Work in mobile browsers (at least for viewing)

**Don't:**
- Require account creation for tutorials
- Auto-play videos
- Lock content behind completed steps
- Time out idle sessions without warning
- Require specific IDE or browser

## Sample Apps and Templates

### Template Strategy

**Tiered approach:**

1. **Minimal example** (Hello World)
   - Single file
   - Zero dependencies beyond your SDK
   - Works in 30 seconds
   - Purpose: Prove the SDK works

2. **Starter template** (Basic app)
   - Simple folder structure
   - Common patterns demonstrated
   - Works in 5 minutes
   - Purpose: Starting point for real projects

3. **Production template** (Full app)
   - Production-ready architecture
   - Auth, error handling, testing included
   - Works in 30 minutes
   - Purpose: Reference implementation

### Template Organization

```
github.com/your-org/
├── examples/
│   ├── minimal/
│   │   ├── node/
│   │   ├── python/
│   │   └── go/
│   ├── starter/
│   │   ├── nextjs/
│   │   ├── express/
│   │   └── fastapi/
│   └── production/
│       ├── saas-starter/
│       └── internal-tool/
```

### Template Maintenance

Templates that don't work are worse than no templates.

**Template health checklist:**
- [ ] CI runs against all templates weekly
- [ ] Dependencies updated monthly
- [ ] SDK version pinned and updated with releases
- [ ] README tested by new contributor quarterly
- [ ] Deprecation notices added before removal

### Real Examples

**Excellent templates: Supabase**
- Templates for multiple frameworks
- One-click deploy to Vercel/Netlify
- Include auth, database, and storage patterns
- Actively maintained

**Excellent templates: Clerk**
- Framework-specific quickstarts
- Complete with authentication flows
- Progressive complexity (minimal → full-featured)

## Handling Onboarding Failures Gracefully

### Common Failure Points

1. **Installation failures**
   - Dependency conflicts
   - Version mismatches
   - Platform-specific issues

2. **Authentication failures**
   - Invalid API key
   - Expired token
   - Wrong environment (test vs production)

3. **First request failures**
   - Network issues
   - CORS problems
   - Rate limiting
   - Invalid request format

### Error Message Design

**Bad error message:**
```
Error: Request failed with status 401
```

**Good error message:**
```
Authentication failed: Invalid API key

Your API key starts with 'sk_test_' but you're calling the production endpoint.

To fix:
1. Use the production API key (starts with 'sk_live_'), or
2. Change endpoint to https://api.example.com/test/

Docs: https://docs.example.com/auth#environments
```

### Proactive Failure Prevention

**Detect common mistakes in real-time:**

```javascript
// Client SDK that catches common errors
if (apiKey.startsWith('sk_test_') && endpoint.includes('/v1/')) {
  console.warn(
    'Warning: Using test API key with production endpoint. ' +
    'This will fail. Use production key or test endpoint.'
  );
}
```

### Recovery Flows

**In-dashboard error recovery:**

```
Something went wrong with your integration.

We detected:
- Last API call: 2 hours ago
- Status: 401 Unauthorized
- Likely cause: API key rotated

[Regenerate API Key] [View Error Logs] [Contact Support]
```

## Measuring Activation Metrics

### Defining Activation

Activation = the moment a developer has enough success to keep using your product.

Different products, different activation definitions:

| Product | Activation Definition |
|---------|----------------------|
| Stripe | First successful test charge |
| Twilio | First SMS sent and delivered |
| Auth0 | First user authenticated |
| Vercel | First deploy accessible via URL |
| Algolia | First search returns results |

### Core Activation Metrics

**Activation rate**
```
Activated users / Signed up users × 100
```
Benchmark: 20-40% for self-serve developer products

**Time to activation**
```
Median time from signup to activation event
```
Benchmark: <10 minutes for APIs, <1 hour for infrastructure

**Activation by cohort**
Track weekly or monthly cohorts to identify improvements:
```
Week 1 cohort: 25% activation
Week 2 cohort: 28% activation (added better error messages)
Week 3 cohort: 35% activation (added interactive tutorial)
```

### Leading Indicators

Track behaviors that predict activation:

| Leading Indicator | Correlation to Activation |
|-------------------|---------------------------|
| Copied API key | 2x more likely |
| Viewed quickstart | 1.5x more likely |
| Installed SDK | 3x more likely |
| Joined Discord | 2.5x more likely |

### Lagging Indicators

Confirm activation led to value:

| Lagging Indicator | Meaning |
|-------------------|---------|
| Day 7 retention | Still using after a week |
| API calls in week 2 | Continued development |
| Upgrade to paid | Perceived enough value |
| Invited team member | Expanding usage |

### Activation Funnel Example

```
Signed up: 1,000
├── Visited dashboard: 950 (95%)
├── Viewed quickstart: 700 (74%)
├── Copied API key: 500 (71%)
├── Made first API call: 350 (70%)
├── Got successful response: 300 (86%)  ← Activation
├── Made 10+ API calls: 150 (50%)
└── Day 7 return: 100 (67%)
```

## Onboarding Email Sequences

### Email Timing

| Email | Timing | Purpose |
|-------|--------|---------|
| Welcome | Immediate | Confirm signup, provide key links |
| Getting started | +1 hour | Drive first API call if not done |
| Tips | +1 day | Share common patterns |
| Check-in | +3 days | Ask if stuck, offer help |
| Activation push | +7 days | Final nudge if not activated |

### Email Content Principles

**Do:**
- Include code snippets (syntax highlighted)
- Link to specific docs pages
- Offer direct reply for help
- Stop sequence once activated

**Don't:**
- Send marketing content during onboarding
- Require clicks to view content
- Send more than one email per day
- Continue sequence after activation

## Examples from Real Developer Tools

### Excellent Onboarding: Stripe

- Test API keys visible immediately
- Interactive "make your first charge" in dashboard
- Language-specific code examples
- Error messages include fix suggestions
- Progress indicator shows completion

### Excellent Onboarding: Railway

- One-click template deploys
- No configuration required for common frameworks
- Live preview URL in seconds
- Clear free tier limits shown

### Excellent Onboarding: Planetscale

- Interactive database explorer
- Import from existing database offered
- SQL examples match your schema
- Branch workflow explained with visuals

### Poor Onboarding Patterns to Avoid

- Multi-step wizards that can't be skipped
- "Complete your profile" blocking code access
- Documentation requiring search to find quickstart
- Quickstarts that assume too much setup
- Error messages without guidance

## Tools

### Onboarding Platforms

- **Appcues** - In-app walkthroughs and checklists
- **Pendo** - Product analytics with onboarding features
- **Userflow** - No-code onboarding flows
- **CommandBar** - Developer-focused command palette with onboarding

### Interactive Documentation

- **CodeSandbox/StackBlitz** - Browser-based code environments
- **Killercoda** - Interactive terminal scenarios
- **ReadMe** - API documentation with "Try It" features
- **Mintlify** - Modern docs with embedded code runners

### Email and Lifecycle

- **Customer.io** - Behavior-triggered emails
- **Loops** - Email for SaaS
- **Intercom** - Chat + email onboarding

### Analytics

- **Amplitude** - Onboarding funnel analysis
- **PostHog** - Open source alternative
- **Heap** - Auto-capture for retroactive analysis

## Related Skills

- `/devmarketing-skills/skills/developer-signup-flow` - Getting to the onboarding start
- `/devmarketing-skills/skills/developer-audience-context` - Who you're onboarding
- `/devmarketing-skills/skills/free-tier-strategy` - What they can do without paying

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: developer-sandbox
description: 'Design and build interactive playgrounds that let developers experience your product without commitment. This skill covers playground architecture, pre-populated examples, embedding strategies, gating decisions, and converting playground users to signups. Trigger phrases: "developer...'
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/developer-sandbox
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Interactive Playgrounds and Demo Environments
## When to Use

Use this skill when you need design and build interactive playgrounds that let developers experience your product without commitment. This skill covers playground architecture, pre-populated examples, embedding strategies, gating decisions, and converting playground users to signups. Trigger phrases: "developer...

Let developers experience your product before they commit. A great playground removes the biggest barrier to adoption: uncertainty about whether your product solves their problem.

## Overview

Developer playgrounds serve multiple purposes:
- **Evaluation**: Let developers test before investing setup time
- **Learning**: Interactive environment for understanding concepts
- **Marketing**: Demonstrate capabilities without sales calls
- **Support**: Reproducible environment for debugging issues

This skill covers designing playgrounds that convert curious visitors into active users.

## Before You Start

Review the **developer-audience-context** skill to understand:
- What do developers want to validate before signing up?
- What's the typical evaluation workflow in your space?
- What competing products offer playgrounds?
- What's the minimum viable experience that demonstrates value?

Your playground should answer the questions developers have when evaluating.

## Playground Design Principles

### Principle 1: Instant Gratification

Developers should see something meaningful within 10 seconds of landing.

**Good**: Page loads with a working example already running
**Bad**: Empty editor with "Type your code here" placeholder

```html
<!-- Good: Pre-loaded, running example -->
<div class="playground">
  <div class="editor">
    <pre><code>// Analyze sentiment of this text
const result = await api.analyze("I love this product!");
console.log(result.sentiment); // "positive"</code></pre>
  </div>
  <div class="output">
    <pre>{ "sentiment": "positive", "confidence": 0.94 }</pre>
  </div>
  <button class="run-btn">Run ▶</button>
</div>
```

### Principle 2: Progressive Complexity

Start simple, let developers go deeper as curiosity grows.

**Level 1: One-Click Demo**
```
[Analyze Text] → See result immediately
```

**Level 2: Editable Input**
```
[Edit the text] → [Run] → See result
```

**Level 3: Full API Access**
```
Edit code → Modify parameters → See raw request/response
```

**Level 4: Full Playground**
```
Multiple files → Import SDK → Build mini-app
```

### Principle 3: Real API, Real Results

Never fake the results. Use your actual API with sandbox credentials.

**Why real matters:**
- Builds trust (not a demo, but actual product)
- Shows real performance characteristics
- Demonstrates actual error handling
- No surprises when they sign up

### Principle 4: Zero Friction

No signup required for basic playground. No installation. No configuration.

```
❌ Bad: "Sign up to try the playground"
❌ Bad: "Install our CLI to continue"
❌ Bad: "Configure your environment..."

✅ Good: Works immediately in browser
```

## Pre-Populated Examples

### Example Selection Strategy

Choose examples that:
1. **Show core value** in 30 seconds
2. **Solve real problems** developers have
3. **Demonstrate differentiation** from competitors
4. **Scale in complexity** from simple to advanced

### Example Categories

**"Hello World" Example**
- Simplest possible use of your API
- Should work with zero modification
- Proves the system is working

```javascript
// Example: Text Analysis API
const result = await api.analyze("Hello, world!");
// Output: { words: 2, characters: 13 }
```

**"Aha Moment" Example**
- Shows unique capability of your product
- Creates the "wow, that was easy" reaction
- This is your most important example

```javascript
// Example: Shows AI doing something impressive
const result = await api.summarize(longArticle);
// Output: A perfect 3-sentence summary
```

**"Real Use Case" Examples**
- Actual scenarios developers encounter
- Shows how to solve specific problems
- Multiple examples for different use cases

```javascript
// Example 1: E-commerce - Analyze product reviews
// Example 2: Support - Classify incoming tickets
// Example 3: Social - Detect spam comments
```

**"Integration" Examples**
- Shows product working with popular tools
- Addresses "will this work with my stack?" concern

```javascript
// Example: Integration with Express.js
app.post('/analyze', async (req, res) => {
  const result = await api.analyze(req.body.text);
  res.json(result);
});
```

### Example Quality Checklist

- [ ] Example runs without modification
- [ ] Output is interesting/impressive
- [ ] Code follows language best practices
- [ ] Comments explain what's happening
- [ ] Real-world use case is obvious
- [ ] Leads to natural "what else can it do?" curiosity

## Sharing and Embedding

### Shareable Playground URLs

Enable developers to share their playground state:

```
https://playground.example.com/?code=BASE64_ENCODED_CODE
https://playground.example.com/share/abc123 (stored state)
```

**Use Cases:**
- Sharing code with teammates
- Linking from Stack Overflow answers
- Bug reports with reproduction
- Code snippets in blog posts

### Embeddable Playgrounds

Let developers embed playgrounds in their own content:

```html
<!-- Embed in documentation -->
<iframe
  src="https://playground.example.com/embed/quickstart"
  width="100%"
  height="400px"
></iframe>

<!-- Or via script tag -->
<div class="example-playground" data-example="quickstart"></div>
<script src="https://playground.example.com/embed.js"></script>
```

### Embedding Considerations

**Size and Performance:**
- Lightweight embed script (< 50KB)
- Lazy-load playground until visible
- Responsive width, configurable height

**Customization:**
- Theme options (light/dark, match host site)
- Show/hide specific UI elements
- Read-only vs. editable modes

**Attribution:**
- Subtle branding that links back
- "Powered by [Product]" footer
- "Edit in full playground" link

## Gating vs. Ungating

### When to Keep Ungated

**Ungated** (no signup required) when:
- Developers are evaluating whether to adopt
- Example demonstrates core product value
- Rate limits can prevent abuse
- Goal is top-of-funnel awareness

### When to Gate

**Gated** (require signup) when:
- Using production API resources
- Accessing personal/saved playgrounds
- Advanced features that require account
- Generating API keys for external use

### Progressive Gating Strategy

```
┌─────────────────────────────────────────────────────────┐
│ UNGATED                                                  │
│ • Run pre-built examples                                │
│ • Edit and re-run examples                              │
│ • Share playground URLs                                 │
├─────────────────────────────────────────────────────────┤
│ FREE SIGNUP                                             │
│ • Save playgrounds                                      │
│ • Get API key for external use                         │
│ • Access more examples                                  │
│ • Higher rate limits                                    │
├─────────────────────────────────────────────────────────┤
│ PAID                                                    │
│ • Production API access                                 │
│ • Team features                                         │
│ • Premium models/features                               │
└─────────────────────────────────────────────────────────┘
```

### Gating UX

When you do gate, minimize friction:

```html
<!-- Good: Non-blocking gate -->
<div class="save-prompt">
  <p>Want to save this playground?</p>
  <button onclick="signup()">Create free account</button>
  <button onclick="dismiss()">Continue without saving</button>
</div>

<!-- Bad: Blocking gate -->
<div class="modal">
  <p>Sign up to continue using the playground</p>
  <form><!-- required fields --></form>
</div>
```

## Playground to Signup Conversion

### The Conversion Funnel

```
Playground Visit
      ↓
Runs First Example (Time to first interaction)
      ↓
Modifies Example (Engagement)
      ↓
Explores More Examples (Interest)
      ↓
Hits Limitation (Trigger)
      ↓
Signs Up (Conversion)
```

### Designing Conversion Triggers

**Natural limitations** that encourage signup:

```javascript
// Rate limit message
"You've used 10/10 free playground requests today.
 Sign up for 1,000 free requests/month."

// Feature tease
"This example uses our Pro model.
 Sign up to try it free."

// Save prompt
"Your playground session will expire in 30 minutes.
 Create an account to save your work."
```

**Avoid artificial friction:**
```javascript
// Bad: Arbitrary block
"Sign up to run more than 3 examples"

// Bad: Feature that should be free
"Sign up to see request/response details"
```

### Conversion Best Practices

**Clear value proposition:**
```
┌─────────────────────────────────────────┐
│ Create a free account                   │
│                                         │
│ ✓ Get your own API key                 │
│ ✓ Save and share playgrounds           │
│ ✓ 1,000 free API calls/month           │
│                                         │
│ [Sign up with GitHub]                   │
│ [Sign up with Google]                   │
│ [Sign up with email]                    │
└─────────────────────────────────────────┘
```

**Preserve context:**
- After signup, return to the same playground state
- Pre-populate API key in their code
- Show "Next steps" relevant to what they were doing

**Measure the funnel:**
```javascript
analytics.track('playground_visit');
analytics.track('playground_first_run');
analytics.track('playground_code_edit');
analytics.track('playground_signup_prompt_shown');
analytics.track('playground_signup_started');
analytics.track('playground_signup_completed');
```

## Playground Architecture

### Client-Side Playgrounds

**Best for:**
- JavaScript/TypeScript SDKs
- Browser-based APIs
- When latency matters

**Architecture:**
```
┌──────────────────────────────────────────┐
│ Browser                                  │
│  ┌─────────────┐    ┌────────────────┐ │
│  │ Monaco      │    │ Preview/Output │ │
│  │ Editor      │ →  │ Iframe        │ │
│  └─────────────┘    └────────────────┘ │
│         ↓                    ↓          │
│  Bundler (esbuild-wasm) → Execute       │
│                              ↓          │
│                        Your API         │
└──────────────────────────────────────────┘
```

### Server-Side Playgrounds

**Best for:**
- Python, Go, Ruby, etc.
- When isolation is critical
- Complex dependencies

**Architecture:**
```
┌────────────────────────────────────────────────┐
│ Browser                                        │
│  ┌─────────────┐    ┌────────────────────┐   │
│  │ Editor      │    │ Output             │   │
│  └─────────────┘    └────────────────────┘   │
│         ↓                    ↑                │
└─────────│────────────────────│────────────────┘
          │                    │
          ↓                    │
   ┌──────────────────────────────────────┐
   │ Backend                              │
   │  ┌────────────┐    ┌─────────────┐ │
   │  │ Code       │ →  │ Sandbox     │ │
   │  │ Receiver   │    │ Container   │ │
   │  └────────────┘    └─────────────┘ │
   └──────────────────────────────────────┘
```

### Security Considerations

**Sandbox isolation:**
- Execute user code in containers
- Limit CPU, memory, network
- No filesystem access to host
- Kill runaway processes

**API protection:**
- Rate limiting per IP/session
- Sandbox-only API credentials
- Monitor for abuse patterns

**Content safety:**
- Scan generated content
- Block malicious outputs
- Log for audit

## Playground UX Components

### Essential UI Elements

```
┌─────────────────────────────────────────────────────────────┐
│ [Examples ▼] [Docs] [Share] [Sign Up]                       │
├───────────────────────────────┬─────────────────────────────┤
│                               │                             │
│  // Your code here            │  Output                     │
│  const result = await         │  {                         │
│    api.analyze("Hello");      │    "sentiment": "neutral"  │
│                               │  }                         │
│                               │                             │
│                               │                             │
├───────────────────────────────┴─────────────────────────────┤
│ [▶ Run]  [Reset]  [Copy Code]  [Copy as cURL]              │
└─────────────────────────────────────────────────────────────┘
```

### Editor Features

- Syntax highlighting
- Autocomplete for SDK methods
- Error highlighting
- Line numbers
- Multiple file support (advanced)

### Output Features

- Formatted JSON
- Collapsible nested objects
- Copy output button
- Request/response toggle
- Timing information

## Tools

### Code Editors
- **Monaco Editor**: VS Code's editor (feature-rich)
- **CodeMirror**: Lightweight, extensible
- **Ace Editor**: Long-standing, battle-tested

### Sandboxing
- **Firecracker**: Lightweight VMs
- **gVisor**: Container sandboxing
- **WebContainers**: Browser-based Node.js

### Playground Platforms
- **CodeSandbox**: Full development environments
- **StackBlitz**: WebContainer-based
- **Replit**: Multi-language support
- **Custom**: Build your own for control

### Embedding
- **iframes**: Simple but limited
- **Web Components**: Better isolation
- **Script embeds**: Most flexible

## Related Skills

- **api-onboarding**: Playground as onboarding tool
- **docs-as-marketing**: Interactive examples in documentation
- **sdk-dx**: SDK design that works in playground context
- **developer-metrics**: Measuring playground effectiveness
- **developer-audience-context**: Understanding what to demo

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: developer-seo
description: 'SEO strategy for technical queries and developer audiences. Covers keyword research for "how to X in language" queries, error message SEO, Stack Overflow-style content, technical long-tail keywords, and competing with official documentation sites. Use when asked about: - SEO for...'
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/developer-seo
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Developer SEO
## When to Use

Use this skill when you need sEO strategy for technical queries and developer audiences. Covers keyword research for "how to X in language" queries, error message SEO, Stack Overflow-style content, technical long-tail keywords, and competing with official documentation sites. Use when asked about: - SEO for...

## Overview

Developer SEO differs fundamentally from traditional SEO. Developers search with precise technical intent—error messages, API questions, "how to X in Y language" queries. They bounce immediately from thin content and respect sites that actually solve problems. Your competition isn't other marketing sites; it's Stack Overflow, official docs, and GitHub issues.

This skill covers SEO strategies that work for technical audiences without compromising on substance.

## Understanding Developer Search Behavior

### How Developers Search

Developers search differently than general audiences:

**Query patterns:**
- Error messages (often copy-pasted verbatim)
- "How to [action] in [language/framework]"
- "[Tool A] vs [Tool B]"
- "[Concept] tutorial"
- "[Library] [specific function] example"

**Behavioral signals:**
- High bounce rates on superficial content
- Long dwell time on genuinely helpful pages
- Multiple tabs open comparing solutions
- Quick scroll to code examples
- Immediate exit if content doesn't match query intent

### Search Intent Categories

1. **Troubleshooting**: Developer has an error, needs a fix
2. **Learning**: Developer wants to understand a concept
3. **Evaluating**: Developer comparing tools or approaches
4. **Implementing**: Developer needs working code examples
5. **Reference**: Developer needs quick syntax or API lookup

## Keyword Research for Developers

### Finding Technical Long-Tail Keywords

Technical long-tail keywords have lower volume but extremely high intent. A developer searching "axios interceptor refresh token react" knows exactly what they need.

**Research approaches:**

1. **Mine your support channels**
   - Extract questions from support tickets
   - Review Discord/Slack community questions
   - Analyze GitHub issues for common problems

2. **Stack Overflow mining**
   - Search for questions mentioning your tool category
   - Look at related questions on popular threads
   - Note the exact phrasing developers use

3. **Google Search Console analysis**
   - Find queries you rank positions 5-20 for
   - Identify question-based queries
   - Spot error message searches hitting your site

4. **Competitor content gaps**
   - What questions do competitors' docs not answer?
   - Where are forum threads unsatisfied with existing answers?

### Error Message SEO

Error messages are SEO gold—developers copy-paste them directly into search.

**Strategy:**
1. Create dedicated pages for common errors
2. Use exact error text in titles and H1s
3. Include the full error message early in content
4. Provide the actual fix, not generic troubleshooting
5. Add related errors users might also encounter

**Content structure for error pages:**
```
Title: [Exact Error Message] - How to Fix

## The Error
[Full error message and where it appears]

## Quick Fix
[The solution that works in most cases]

## Why This Happens
[Brief technical explanation]

## Other Solutions
[Alternative fixes for edge cases]

## Related Errors
[Links to similar issues]
```

### Competing with Official Documentation

Official docs have domain authority advantages but often have weaknesses:

**Where docs often fail:**
- No "why" explanations, just "what"
- Missing real-world examples
- No troubleshooting guides
- Outdated content
- No comparative context

**Your opportunities:**
- "Getting started with X" tutorials that hold your hand
- "X vs Y" comparison content (docs never compare)
- Migration guides between versions or tools
- Real-world implementation examples
- Common gotchas and how to avoid them

## Content Formats That Rank

### How-To Guides

Structure for technical how-to content:

```markdown
# How to [Action] in [Technology]

## Prerequisites
- What you need before starting
- Required versions/dependencies

## Quick Version (TL;DR)
- Code snippet that works for common case

## Step-by-Step
1. Step with explanation
2. Step with code example
3. Step with expected output

## Complete Example
[Full working code]

## Common Issues
- Problem 1: Solution
- Problem 2: Solution

## Next Steps
[What to learn next]
```

### Comparison Content

Developers actively search "[Tool A] vs [Tool B]" when evaluating options.

**Guidelines:**
- Be genuinely objective (developers will check)
- Include actual code comparisons
- Cover specific use cases where each wins
- Mention your tool's limitations honestly
- Update when tools change significantly

### Tutorial Series

In-depth tutorials build topical authority and capture multiple related queries.

**Planning approach:**
1. Identify a topic cluster (e.g., "authentication in Node.js")
2. Create pillar content covering the broad topic
3. Build supporting content for specific subtopics
4. Interlink strategically

## Technical SEO for Developer Sites

### Code Snippet Optimization

Google can read and understand code. Optimize for it:

- Use semantic HTML (`<code>`, `<pre>`)
- Add language hints for syntax highlighting
- Ensure code is actual text, not images
- Test that code actually works (broken examples hurt credibility)

### Page Speed for Developer Sites

Developers expect fast sites. They also often use ad blockers and privacy tools.

**Priorities:**
- Minimize JavaScript for documentation pages
- Ensure content loads without JS when possible
- Optimize for low-bandwidth scenarios (conference Wi-Fi)
- Test with developer-typical browser extensions enabled

### Documentation Site Architecture

Good IA helps both users and search engines:

- Clear hierarchy (Guides > Category > Specific Topic)
- Breadcrumbs for navigation
- Consistent URL structures
- Proper use of canonical tags for versioned docs
- XML sitemaps for large doc sites

## Building Authority

### Technical Backlinks

High-quality technical backlinks matter more than quantity.

**Sources that work:**
- GitHub repository READMEs
- Technical blog posts citing your content
- Stack Overflow answers linking to your guides
- Developer newsletter mentions
- Conference talk resource lists

**What doesn't work:**
- Generic guest posting
- Link exchanges
- Directory spam
- Forum signature links

### Content Freshness

Developer content becomes outdated quickly:

- Review and update major guides quarterly
- Add "last updated" dates (developers check these)
- Create processes for updating when dependencies change
- Remove or redirect genuinely obsolete content

## Measuring Developer SEO

### Metrics That Matter

- Organic traffic to documentation and guides
- Rankings for target technical queries
- Time on page for tutorial content
- Search Console impressions for error message queries
- GitHub referrals from technical content

### Metrics to Interpret Carefully

- Bounce rate (developers often find answer and leave—that's success)
- Pages per session (for reference content, one page is fine)
- Conversion rate (long attribution windows for developer tools)

## Budget and Resources

### Minimum Viable Approach
- **Time investment**: 5-10 hours/week for content creation
- **Tools needed**: Google Search Console (free), basic keyword research tool
- **Timeline**: 3-6 months to see meaningful organic growth

### Scaled Approach
- Dedicated technical content writer
- SEO tools subscription (Ahrefs, Semrush)
- Content management system optimized for docs
- Regular content audits and updates

## Tools

- **Google Search Console**: Track rankings and discover query opportunities
- **Ahrefs/Semrush**: Keyword research and competitor analysis
- **Screaming Frog**: Technical SEO audits for documentation sites
- **Algolia**: Search analytics revealing what developers look for
- **Octolens**: Monitor developer discussions to find content opportunities and questions your content should answer

## Common Mistakes

1. **Writing for search engines, not developers**: Keyword-stuffed content that doesn't actually help
2. **Ignoring search intent**: Ranking for queries but not matching what developers actually need
3. **Thin content**: Short posts that don't provide real value
4. **Outdated examples**: Code that no longer works in current versions
5. **No unique value**: Rehashing what official docs already cover

## Related Skills

- **developer-content-strategy**: Overall content planning for developer audiences
- **dev-tool-directory-listings**: Building domain authority through directory presence
- **developer-lead-gen**: Converting organic traffic into leads

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.