---
name: Writing for Developers
description: This skill should be used when the user asks to "write an article", "help me write a blog post", "draft a technical article", "review my article", "check my writing", "improve this draft", "give me writing feedback", "find a topic", "what should I write about", or mentions "writing coach". Provides comprehensive guidance including topic selection, 17 writing skills, and reviewer collaboration from "Writing for Developers" by Piotr Sarna & Cynthia Dunlop.
version: 2.0.0
---

# Technical Article Writing Coach

A comprehensive writing coach skill based on "Writing for Developers: Blogs that get read" by Piotr Sarna & Cynthia Dunlop. Guides users through topic selection, drafting, review, and publishing.

## Topic Selection (Before Everything)

**The 3 Ps Test** - Does your topic meet at least one?
- **Proud of** - Accomplishments you're eager to show off
- **Pained by** - Challenges that caused constant headaches
- **Passionate about** - What gets your blood racing

If you're not personally proud, pained, or passionate about the topic, the blog post won't yield great results.

See `references/topic-selection.md` for topic idea sources and testing methods.

## The 15 Core Writing Skills

### Pre-Writing Phase

**1. Goal Definition** - Before writing, establish:
- "The goal of this article is to..." (never published)
- "My perspective is interesting because..." (never published)
- Who is the target reader? What do they already know?

**2. Pattern Selection** - Match content to the right structure:

| Content Type | Pattern |
|-------------|---------|
| Finding/fixing a tricky bug | Bug Hunt |
| Migrating to new language/framework | Rewrote It in X |
| Significant technical project | How We Built It |
| Hard-won wisdom from experience | Lessons Learned |
| Opinion on industry direction | Thoughts on Trends |
| Educational content with product | Non-markety Product |
| Performance data/comparisons | Benchmarks |

### Writing Phase

**3. Evidence-Based Claims** - Support every statement with specifics
**4. Conversational Voice** - Write authentically, not robotically
**5. Single-Idea Paragraphs** - One idea per paragraph
**6. Scannability** - Headings, bold key points, lists/tables
**7. Show Don't Tell** - Code, diagrams, specific numbers
**8. Actionable Writing** - Don't make reader think

See `references/actionable-writing.md` for transforming abstract → actionable.

### Review Phase (The 3 F's)

**9. Facts Check** - Is each claim supported by evidence?
**10. Focus Check** - Does every paragraph advance the goal?
**11. Flow Check** - Logical progression? Smooth transitions?
**12. Component Review** - Title, intro, headings, ending, code, visuals
**13. Pattern-Specific Review** - Apply criteria for chosen pattern
**14. Pre-Publish Verification** - Links, code, images, metadata
**15. Self-Review Test** - Would I share this if someone else wrote it?

## Human Voice (Avoiding AI-Sounding Writing)

Check for AI red flags:
- Unusually dense/consistent metaphors
- Overly flowery, consistently ornate prose
- Lack of specific technical details
- Artificial emotional arc
- **Excessive em dashes (—)** - Classic AI tell

To sound human:
- Include specific, idiosyncratic details
- Admit mistakes, uncertainties, frustrations
- Let voice vary naturally
- Include self-deprecating comments

See `references/human-voice.md` for detailed guidance.

## Working with Reviewers

**Selecting reviewers:**
- Technical reviewer (knows subject matter)
- Clarity reviewer (unfamiliar with topic)

**Preparing reviewers:**
- Provide background on goal and target reader
- Specify what feedback you want

See `references/working-with-reviewers.md` for detailed guidance.

## Workflow for Writing New Articles

1. **Topic Selection** - Apply the 3 Ps test
2. **Goal Definition** - Write goal and differentiator sentences
3. **Pattern Selection** - Match to appropriate pattern
4. **Draft** - Focus on getting ideas down fast
5. **Optimize** - Apply the 3 F's (Facts, Focus, Flow)
6. **Review** - Get feedback from reviewers
7. **Ship** - Final checks and publish

## Coaching Prompts

**Stuck starting:**
> "Start with the most interesting technical part. What's the one thing you most want to share?"

**Too much content:**
> "Go back to your goal statement. Does this paragraph advance that goal? If not, cut it."

**Doubts expertise:**
> "You're the world's expert on YOUR specific experience. Share what you learned."

## Additional Resources

### Reference Files

- **`references/topic-selection.md`** - The 3 Ps test, topic idea sources
- **`references/writing-skills-complete.md`** - Full skills reference with all details
- **`references/actionable-writing.md`** - Transform abstract → actionable
- **`references/human-voice.md`** - Sound human, not AI-generated
- **`references/native-english-style.md`** - Sentence optimization, clarity
- **`references/seo-metadata.md`** - Keywords, titles, meta descriptions
- **`references/visual-code-presentation.md`** - Headings, images, code
- **`references/working-with-reviewers.md`** - Selecting and working with reviewers
- **`references/pattern-examples.md`** - Real-world blog post examples