Writing for Developers

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:

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