jonathimer/devrel-content

DevRel Content

This skill helps you create technical content that developers actually read: blog posts, tutorials, documentation, and thought leadership pieces that build trust and drive adoption.

---

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)
• Their pain points (what problems resonate)
• Verbatim language (how they describe things)
• Voice & tone (how formal/technical to be)

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

---

The DevRel Content Framework

Phase 1: Research & Validation

Before writing anything, validate the topic is worth writing about.

| Research Type | What to Do | |--------------|------------| | Search intent | Google your topic. What already ranks? What's missing? | | Community signals | Search Reddit, HN, Stack Overflow. Are developers asking about this? | | Competitor gaps | What have competitors written? What haven't they covered? | | Internal data | Support tickets, Discord questions, GitHub issues about this topic | | Keyword research | Use Ahrefs/SEMrush for search volume on technical terms |

Red flags — Don't write if:

• You're the only one who cares about this topic
• 10 identical articles already exist
• The topic is too broad ("Introduction to JavaScript")
• The topic is too narrow (no search volume, no community interest)

Phase 2: Content Type Selection

Choose the right format for your goal:

| Content Type | Best For | Structure | |-------------|----------|-----------| | Tutorial | Teaching a specific skill | Step-by-step, code-heavy | | Guide | Covering a topic comprehensively | Sections, reference material | | Comparison | Helping with decisions | Table-based, pros/cons | | Announcement | Launching features/products | News lead, what/why/how | | Thought leadership | Building authority | Opinion, predictions, takes | | Case study | Social proof | Problem → Solution → Results | | Troubleshooting | Solving specific errors | Error → Cause → Fix |

Phase 3: Outline Structure

Use this outline template:

# [Title that promises specific value]

## Hook (2-3 sentences)
- State the problem or opportunity
- Establish credibility ("We migrated 10,000 repos...")
- Promise what the reader will learn

## Context (optional)
- Brief background if needed
- Link to prerequisites

## The Meat
### Section 1: [First major concept]
- Explanation
- Code example
- Common pitfall

### Section 2: [Second major concept]
- Explanation
- Code example
- Real-world application

### Section 3: [Third major concept]
- Explanation
- Code example
- Advanced tip

## Putting It Together
- Complete example
- Working code

## What's Next
- Links to deeper content
- Call to action (try the product, join Discord, etc.)

---

Writing Code Examples

Code is the content. Get it right.

The Copy-Paste Test

Every code example must:

| Requirement | Why It Matters | |------------|----------------| | Run without modification | Developers will copy-paste. If it fails, you lose trust. | | Include imports | Don't assume they know which libraries to import. | | Show output | What should they see when it works? | | Handle errors | Real code has error handling. Show it. | | Use real values | No foo, bar, example.com unless necessary. |

Code Example Structure

First, install the dependencies:

\`\`\`bash
npm install your-library axios
\`\`\`

Now create a file called `fetch-data.js`:

\`\`\`javascript
// fetch-data.js
import { Client } from 'your-library';
import axios from 'axios';

const client = new Client({
  apiKey: process.env.YOUR_API_KEY // Use environment variables
});

async function fetchUserData(userId) {
  try {
    const user = await client.users.get(userId);
    console.log(`Fetched user: ${user.name}`);
    return user;
  } catch (error) {
    console.error(`Failed to fetch user: ${error.message}`);
    throw error;
  }
}

// Example usage
fetchUserData('user_123')
  .then(user => console.log(user))
  .catch(err => process.exit(1));
\`\`\`

Run it:

\`\`\`bash
YOUR_API_KEY=sk_test_xxx node fetch-data.js
\`\`\`

Expected output:

\`\`\`
Fetched user: Jane Developer
{ id: 'user_123', name: 'Jane Developer', email: '[email protected]' }
\`\`\`

Language-Specific Conventions

| Language | Code Block | Package Install | Env Vars | |----------|-----------|-----------------|----------| | JavaScript/Node | javascript or js | npm install | process.env.VAR | | TypeScript | typescript or ts | npm install | process.env.VAR | | Python | python or py | pip install | os.environ['VAR'] | | Go | go | go get | os.Getenv("VAR") | | Rust | rust | cargo add | std::env::var("VAR") | | Shell | bash or shell | N/A | $VAR |

---

Technical Accuracy Checklist

Run through before publishing:

| Check | How to Verify | |-------|---------------| | Code runs | Copy-paste every snippet and run it | | Versions match | Are you using the current library version? | | Links work | Click every link | | Commands work | Run every CLI command | | Screenshots current | Do UI screenshots match the current product? | | No deprecated APIs | Check if any APIs used are deprecated | | Security review | No hardcoded secrets, SQL injection, etc. | | Peer review | Have an engineer read it for accuracy |

---

SEO for Developer Content

Developers use Google differently than consumers.

Developer Search Patterns

| Pattern | Example Searches | |---------|-----------------| | Error messages | "TypeError: Cannot read property 'map' of undefined" | | How to | "how to deploy next.js to vercel" | | Comparison | "prisma vs typeorm 2024" | | Best practices | "typescript project structure best practices" | | Alternatives | "alternatives to firebase" | | With | "react with typescript tutorial" |

Technical SEO Checklist

| Element | Best Practice | |---------|--------------| | Title | Include primary keyword, framework names, year if relevant | | Meta description | 150 chars, include keyword, promise specific outcome | | H1 | Match or closely match title | | H2s | Include secondary keywords, make scannable | | Code blocks | Use proper syntax highlighting (helps featured snippets) | | Internal links | Link to related docs, tutorials, API reference | | External links | Link to official docs of tools mentioned | | URL slug | Lowercase, hyphens, include keyword |

Example Optimized Title

| Bad | Good | |-----|------| | "Using Our API" | "How to Authenticate with the YourProduct API (Node.js)" | | "Database Guide" | "PostgreSQL Connection Pooling: Complete Guide with pgBouncer" | | "Getting Started" | "Getting Started with YourProduct: Your First API Call in 5 Minutes" |

---

Content Quality Signals

What separates great devrel content from mediocre:

Do This

• Show, don't tell — Code over prose
• Address the "why" — Not just how to do it, but when and why
• Acknowledge tradeoffs — Nothing is perfect; developers respect honesty
• Link to sources — Official docs, RFCs, related articles
• Include dates — "Updated March 2024" or version numbers
• Progressive disclosure — Start simple, add complexity
• Real examples — Production scenarios, not just hello world

Don't Do This

• Wall of text — Break up with code, headers, bullets
• Marketing speak — "Best-in-class," "seamless," "revolutionary"
• Assuming knowledge — Define acronyms, link to prerequisites
• Outdated content — Nothing worse than a 2019 tutorial with deprecated APIs
• Buried lede — Put the answer first, explanation second
• No code — Developers came for code, not prose

---

Content Templates

Blog Post Template

# [Specific, keyword-rich title]

[2-3 sentence hook: problem + promise]

## The Problem

[1 paragraph explaining the pain point]

## The Solution

[Brief explanation of your approach]

### Step 1: [Action]

[Explanation]

\`\`\`language
// Code
\`\`\`

### Step 2: [Action]

[Explanation]

\`\`\`language
// Code
\`\`\`

### Step 3: [Action]

[Explanation]

\`\`\`language
// Code
\`\`\`

## Complete Example

\`\`\`language
// Full working code
\`\`\`

## Troubleshooting

### [Common Error 1]
[Solution]

### [Common Error 2]
[Solution]

## What's Next

- [Link to deeper dive]
- [Link to related tutorial]
- [CTA: Try it yourself]

Comparison Post Template

# [Tool A] vs [Tool B]: [Specific Use Case] ([Year])

[1 paragraph: Who this comparison is for and what you'll learn]

## Quick Comparison

| Feature | Tool A | Tool B |
|---------|--------|--------|
| [Feature 1] | | |
| [Feature 2] | | |
| [Feature 3] | | |

## When to Choose [Tool A]

- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

## When to Choose [Tool B]

- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

## Deep Dive: [Specific Aspect]

### Tool A Approach
[Explanation + code]

### Tool B Approach
[Explanation + code]

## Our Recommendation

[Specific guidance based on use case]

---

Measuring Content Success

Metrics to Track

| Metric | What It Tells You | |--------|------------------| | Page views | Reach (but vanity without context) | | Time on page | Engagement (are they reading?) | | Scroll depth | Did they read to the end? | | Bounce rate | Did they find what they needed? | | Search rankings | SEO performance | | Backlinks | Authority and reference value | | Social shares | Resonance (especially HN, Twitter, Reddit) | | Conversion events | Sign-ups, installs, docs clicks |

Content → Conversion Path

Track the journey:

1. Search/social → Blog post
2. Blog post → Docs / quickstart
3. Docs → Sign up / install
4. Sign up → Activation (first success)

---

Tools

| Tool | Use Case | |------|----------| | Octolens | Monitor where your content gets shared (HN, Reddit, Twitter). Track competitor content performance. Find content ideas from developer conversations. | | Grammarly / Hemingway | Readability and grammar checking | | Carbon / Ray.so | Beautiful code screenshots | | Excalidraw | Technical diagrams | | Loom | Quick video walkthroughs | | Ahrefs / SEMrush | Keyword research and SEO tracking | | Google Search Console | Track search performance |

---

Related Skills

• developer-audience-context — Foundation for knowing your readers
• technical-tutorials — Deep dive into step-by-step content
• developer-newsletter — Distributing content via email
• developer-seo — Technical SEO optimization
• hacker-news-strategy — Sharing content on HN effectively