Technical Article Writer

Technical Article Writer

Write technical articles that developers actually want to read. This skill combines structural frameworks from technical writing, hook engineering from copywriting, and practitioner-tested patterns for developer content.

Core philosophy

Most technical articles fail because of structural problems, not bad ideas: burying the lede, mixing content types, weak openings, no clear motivation, or trying to cover too much.

Developer audiences have a built-in BS detector. The best technical content leads with specificity and honesty. It sounds like a smart colleague explaining something interesting, not a marketer pitching. Acknowledge your expertise level, solve a specific problem, use real examples.

---

Workflow

Follow these phases in order. Each phase produces a concrete artifact the user reviews before moving on. Phase 1 is mandatory — always ask the user the intake questions and wait for answers before writing anything. If the user already provided some context, extract what you can and ask only about missing pieces.

Phase 1: Idea sharpening (interview)

Stop and ask. Before writing anything, present the intake questions below to the user and wait for their answers. Do not skip this phase, do not infer silently, and do not start drafting until you have explicit answers or confirmation on every item. Ask the user (or extract from context and confirm):

1. Topic: What specific thing are you writing about? 2. Objective: What's the primary goal of this article? Use AskUserQuestion to present these options (push back if the user picks more than one — a single primary CTA converts far better than competing asks):

• Newsletter subscription / audience growth
• Personal branding / thought leadership / authority in a niche
• Product or service signup / free trial
• Direct purchase
• Lead generation (download, gated asset, whitepaper)
• Demo or sales call booking
• Community join (Discord, Slack, forum)
• Engagement (reply, share, comment, restack)
• Reader support (paid subscription, tip, sponsorship)
• No conversion goal (purely informational / educational)

The objective shapes the CTA, how much you give away vs. tease, and where conversion points sit. It will be passed directly to the copywriting-cta skill in Phase 5b.

3. Audience: Who reads this? (junior devs, senior engineers, CTOs, general tech, DBA, frontend developer...) 4. Content type: Which pattern fits? (see references/article-structures.md for full templates)

• The Bug Hunt / We Rewrote It in X / How We Built It / Lessons Learned
• Thoughts on Trends / Benchmark / Tutorial / Explainer

5. Length target: Short (800-1200), Medium (1500-2500), Long (3000+) 6. One-sentence thesis: The single claim or takeaway. If the user can't state this, help them.

If the user already provided most of this, extract from conversation and confirm. But if critical pieces are missing, stop and ask before proceeding. Don't guess at the audience, content type, or thesis. A wrong assumption here wastes an entire draft.

Specifically:

• If the topic is vague ("write about Java performance"), ask what specific aspect and what the reader should walk away knowing.
• If the audience is unclear, ask. A post for junior devs has a completely different structure than one for senior engineers.
• If you can't infer a thesis, ask the user: "What's the one thing you want the reader to remember?" If they can't answer, help them find it through questions about what surprised them, what they'd tell a colleague, or what they wish they'd known earlier.
• If the content type is ambiguous (could be a tutorial or an explainer), ask which experience the reader should have: following along hands-on, or building a mental model.

Only proceed to Phase 2 once you have enough clarity on topic, audience, content type, and thesis to write a coherent outline. It's cheaper to ask one question now than to rewrite 2000 words later.

Idea quality filters. Apply these before investing in a draft:

Julia Evans's heuristic: the best technical content comes from what you struggled with, not what you mastered. If the topic feels too "textbook", push toward the specific struggle, surprise, or counterintuitive finding.

Julian Shapiro's novelty filter. The idea should fit at least one:

• Counter-intuitive: "I never realized the world worked that way"
• Counter-narrative: "That's not how I was told it worked"
• Shock and awe: "I had no idea that was possible"
• Elegant articulation: "I always felt that way but couldn't put it into words"
• Makes you feel seen: "Finally someone gets my experience"

If the idea doesn't pass any filter, say so. Help the user find the angle that does.

Phase 2: Title generation

Generate 10 title variants using different hook strategies. Read references/hooks-and-titles.md for the full framework of 10 hook types and headline formulas.

Constraints for developer audiences:

• 7-12 words optimal for LinkedIn/B2B sharing
• Specificity over cleverness ("How to profile Go allocations with pprof" > "Mastering Go Performance")
• Numbers and data signal rigor
• Avoid superlatives ("ultimate", "complete", "everything you need")
• Technical keywords attract the right audience
• Cognitive dissonance creates curiosity without clickbait

Present 10 titles ranked by assessment, with a brief note on why each works. Let the user pick or remix.

Phase 3: Hook and intro

Delegate the hook to the `copywriting-hooks` skill. Pass the topic, audience, language, content type, and length target from Phase 1. The skill will propose 3-4 hook options (2 candidates each) and wait for the user to pick. Do not write the hook yourself — let the skill run its full workflow.

After the user picks a hook, write the remaining intro (2-3 paragraphs) around it:

1. Hook (chosen by the user via copywriting-hooks) 2. Stakes (1-2 sentences): Why should the reader care? What's the cost of not knowing this? 3. Promise (1 sentence): What will the reader gain by the end?

Address three reader objections:

• Untrustworthy: Why should I listen to you? (credibility hook or specific experience)
• Irrelevant: Why does this matter to me? (stakes)
• Implausible: Will this actually deliver? (promise + specificity)

Anti-patterns to avoid:

• Starting with a dictionary definition
• "In today's fast-paced world..."
• "Have you ever wondered..."
• Burying the interesting part after 3 paragraphs of context
• Explaining what the article will cover instead of demonstrating value

Phase 4: Body structure

Choose structure based on content type. Read references/article-structures.md for detailed templates per content type.

General structural principles:

• One idea per section. If a section does two things, split it.
• Show, then tell. Lead with the example, code snippet, or observation. Then explain.
• Progressive disclosure. Start with the simplest version, then add complexity.
• Every section earns the next. Each section should create enough momentum to pull the reader forward. If a section could be skipped, cut it.

For code-heavy articles:

• Snippets < 20 lines, focused on one concept
• Always show "before" (problem) and "after" (solution)
• Annotate non-obvious lines
• Link to repo for full code, show only the interesting parts inline

For opinion/analysis:

• Steelman the opposing view before arguing against it
• Concrete examples, not abstract reasoning
• Quantify claims ("2x faster" not "much faster")

Phase 5: Draft the full article

Write the complete article. Interleave hook, body sections, and conclusion.

For the conclusion, avoid restating the article. Instead pick one of:

• Implication: What does this mean for the reader's work going forward?
• Open question: What's still unresolved or worth exploring?
• Call to action: What should the reader do next?

Phase 5b: CTA

Delegate to the `copywriting-cta` skill. Pass the objective from Phase 1 as the primary objective. The skill will interview the user for any missing inputs (article context, audience relationship, funnel stage, mechanism) and produce the complete CTA recommendation — copy, form, mechanism, A/B test plan, and accessibility check.

Place the CTA output at the end of the article, after the conclusion. Do not write a CTA yourself.

Phase 5c: Humanize

Invoke a humanizer skill (e.g. "humanize", "humanizer", "de-slop", "natural writing check", "AI detection cleanup", "rewrite like a human") to strip AI-generated patterns — filler words, predictable cadence, over-hedging, hollow transitions, inflated language. Developer audiences have a built-in BS detector; AI-sounding prose kills trust before the reader reaches the technical content.

Preserve the hook and title. The opening hook (Phase 3) and title (Phase 2) were deliberately engineered for curiosity and credibility. Instruct the humanizer to leave them intact — rewriting them for "naturalness" destroys the copywriting structure that earns the click and the first scroll.

Phase 6: Image suggestions

After the draft is complete, suggest 1-3 images with specific placement in the article. For each image, provide:

• Placement: Where in the article (e.g. "as the hero/cover image", "after the intro", "between section X and Y")
• Purpose: What the image adds (break up a long text section, illustrate a concept, set the tone, visualize data)
• Description: What the image should depict

Offer to generate a Midjourney prompt for each suggested image. If the user accepts, use the latest Midjourney model conventions to write the prompt. Use --ar 16:9 or --ar 3:1 for hero/cover images and wide illustrations (optimal for article headers), --ar 3:2 for smaller inline images. Refer to up-to-date Midjourney documentation for current prompt syntax and parameters.

Phase 7: Title finalization

Revisit titles from Phase 2. Now that the full piece exists, some titles fit better. Present top 3 with a recommendation.

---

Output format

Present the article in clean markdown with:

• The chosen title as H1
• A subtitle or meta-description (1 sentence)
• The full article body
• Image suggestions with placement notes (and Midjourney prompts if accepted)
• A "Title alternatives" section at the end with 2-3 runner-up titles
• A social teaser (only if the user accepted — offer after the draft, don't auto-generate)

---

Reference files

Read these when the corresponding phase needs more depth:

• references/hooks-and-titles.md -- The 10 hook types, 6 copywriting frameworks (PAS, AIDA, BAB, FAB, PASTOR, 4Us), headline formulas, and research data. Read during Phase 2 and Phase 3.
• references/article-structures.md -- Detailed templates for each of the 8 content types, Diataxis framework, structural anti-patterns, and transition techniques. Read during Phase 4.

Article Structures Reference

Table of Contents

1. Eight Content Type Templates 2. The Diataxis Framework 3. Structural Anti-patterns 4. Section Transitions

---

1. Eight Content Type Templates

Each template defines sections, purpose, and approximate word allocation for a medium-length article (1500-2500 words). Adapt proportions to target length.

The Bug Hunt

Debugging narrative. The reader follows your investigation like a mystery.

1. The symptom (10%): What went wrong? Error messages, metrics, user reports. 2. First hypothesis (15%): What you assumed. Why it seemed reasonable. 3. The investigation (30%): What you tried. Dead ends matter. Show commands, logs, code. 4. The revelation (20%): The actual root cause. The payoff. Make it vivid. 5. The fix (15%): Code, config, architecture change. 6. The lesson (10%): The generalizable insight beyond this specific bug.

Technique: Build tension with plausible-but-wrong hypotheses before the real cause.

We Rewrote It in X

Migration story. Readers want: should I do this too?

1. Why we considered the rewrite (15%): The pain. Be honest. 2. Why we chose [new thing] (10%): Decision criteria. What was rejected. 3. The migration process (30%): How. Phased? Big bang? Tooling? 4. What went wrong (15%): The pain. This is what makes it credible. 5. Results and metrics (20%): Before/after. Quantify everything. 6. Would we do it again? (10%): Honest assessment. Under what conditions?

Technique: The "what went wrong" section is what makes this valuable. Without it, it's a press release.

How We Built It

Architecture walkthrough. Readers want design decisions.

1. What and why (10%): Product/system goal. User needs. 2. Constraints (15%): Performance targets, team size, timeline, compatibility. 3. Architecture overview (20%): High-level design. Diagram if possible. 4. Key decisions and tradeoffs (30%): For each: options, choice, and why. Core value. 5. What we'd change (15%): Hindsight. What would v2 look like? 6. Takeaways (10%): Principles the reader can apply.

Technique: Frame each decision as a tradeoff, not the "right" answer.

Lessons Learned

Retrospective insight.

1. Context (10%): What experience generated these lessons. Credibility. 2. Lesson 1 (20%): Most surprising or important. Lead with your best. 3. Lesson 2 (20%): Build on or contrast with Lesson 1. 4. Lesson 3 (20%): The one that took longest to learn. 5. Lesson N (if needed): Keep to 3-5 lessons. More dilutes impact. 6. The meta-lesson (10%): What ties these together.

Technique: Each lesson needs a specific story, not just the abstract principle.

Thoughts on Trends

Industry analysis or opinion piece.

1. The observation (15%): What you're noticing. Be concrete. 2. Evidence (25%): Data, examples, trends. 3. The steelman (15%): Strongest argument against your position. Address honestly. 4. Your thesis (25%): Your take, informed by evidence and counterargument. 5. Implications (20%): What should the reader do differently?

Technique: The steelman separates good analysis from hot takes.

Benchmark / Data-Driven

Technical comparison or measurement.

1. What and why (10%): The question. Why it matters. 2. Methodology (20%): Environment, tools, config. Reproducible detail. 3. Results (25%): Data first, interpretation second. Tables, charts, numbers. 4. Analysis (25%): What it means. Caveats. Where methodology might mislead. 5. Practical recommendations (15%): Given this data, what should the reader do? 6. Reproduction notes (5%): Repo, scripts, raw data links.

Technique: Lead with methodology. No trust in setup = no trust in conclusions.

Tutorial / How-To

Step-by-step guide.

1. What you'll build/achieve (5%): End result. Screenshot or demo if possible. 2. Prerequisites (5%): What the reader needs. Be explicit. 3. Steps (70%): Numbered, sequential. Each step: action, code/command, expected result, common errors. 4. Verification (10%): How to confirm it worked. 5. Next steps (10%): Related topics, advanced usage.

Technique: Test from scratch on a clean environment. Every missing step loses readers.

Explainer / Deep Dive

Concept explanation for a technical audience.

1. Why this matters (10%): Motivation. What problem does understanding this solve? 2. The simple mental model (20%): The 80/20 explanation. Standalone value. 3. Going deeper (40%): Nuances, edge cases, implementation details. Progressive complexity. 4. Common misconceptions (15%): What people get wrong. Cements understanding. 5. Practical implications (15%): How does knowing this change what you do?

Technique: Start with the simplest accurate mental model, then complicate it.

---

2. The Diataxis Framework

For content closer to documentation than opinion, use Diataxis (Daniele Procida) to diagnose type:

Common failure: mixing types. A tutorial drifting into reference, a how-to explaining theory. Fix: separate mixed content into its proper type.

For blog posts: tutorials need clear start/end states, how-tos solve specific problems without teaching theory, explanations build understanding without requiring action, reference rarely works as a blog post (put it in docs).

---

3. Structural Anti-patterns

• Burying the lede: Interesting insight in paragraph 5. Move it to paragraph 1.
• The unnecessary preamble: 200 words of "In today's world of..." before content. Cut it.
• The kitchen sink: Covering everything about a topic. Pick one angle, go deep.
• Unexplained jargon: Terms without definitions. Not everyone has your context.
• Missing motivation: Explaining "how" without "why anyone should care."
• The wall of code: 50-line block with no annotation. Break up, explain interesting parts.
• The false conclusion: "In conclusion, [restate]." Add value: implications, open questions, CTA.
• Monotone pacing: Every section same length/intensity. Vary rhythm.
• No signposting: Reader doesn't know where they are. Use subheadings and transitions.

---

4. Section Transitions

Techniques that create momentum:

• Forward reference: "But this creates a new problem..."
• Question: "So if X is true, what happens when we try Y?"
• Contrast: "That handles the common case. Edge cases are where it gets interesting."
• Escalation: "This works for small datasets. Let's scale it up."

Momentum killers:

• "Now let's talk about..." (no reason to continue)
• "Another important topic is..." (disconnected)
• "Moving on to..." (filler)

Hooks and Titles Reference

Table of Contents

1. The 10 Hook Types 2. Copywriting Frameworks for Article Intros 3. Headline Formulas and Data 4. The 4 U's Headline Checklist 5. Developer-Specific Constraints 6. Open Loop Technique

---

1. The 10 Hook Types

Based on Neal O'Grady's taxonomy, reverse-engineered from thousands of viral posts. Pick the type that matches your article's angle.

Type 1: Credibility

Signal authority or experience worth listening to.

Patterns:

• "I've [verb] [impressive thing] for [time period]. Here's what I learned."
• "After [specific result], I can tell you [insight]."
• "[Number] years of [activity]. [Number] [things done]. Here's the pattern."

Best for: How We Built It, Lessons Learned, Benchmarks

Type 2: Fear (FOMO/FOBO)

Highlight what the reader risks missing or getting wrong.

Patterns:

• "Most [audience] don't realize [costly mistake]."
• "If you're still doing [common practice], you're leaving [value] on the table."
• "[Percentage] of [audience] get this wrong."

Best for: Counter-narrative articles, opinionated takes

Type 3: Curiosity

Open an information gap the reader must close.

Patterns:

• "There's a [specific thing] that [unexpected property]."
• "I found [thing] that changes how I think about [topic]."
• "What happens when you [unusual action]?"

Best for: Deep dives, experiments, bug hunts

Type 4: Counter-narrative

Challenge what everyone assumes is true.

Patterns:

• "Everyone says [common belief]. They're wrong."
• "The conventional wisdom about [topic] is backwards."
• "[Popular advice] is actively harmful. Here's the evidence."

Best for: Opinion pieces, industry analysis, myth-busting

Type 5: Eloquence

Say something the reader has felt but never articulated.

Patterns:

• "[Elegant reframe of common experience]."
• "The real reason [thing happens] isn't [obvious reason]."

Best for: Philosophical/reflective technical content

Type 6: Faces (Social proof)

Reference known people, companies, or projects.

Patterns:

• "How [known company] solved [problem]"
• "[Known person] said [thing]. Here's why that matters."

Best for: Case studies, analysis of public systems

Type 7: Value

Promise a specific, tangible benefit.

Patterns:

• "[Specific technique] that will save you [specific time/effort]."
• "The [number]-step process I use to [desirable outcome]."

Best for: Tutorials, how-tos, tool recommendations

Type 8: Surprise

Lead with something genuinely unexpected.

Patterns:

• "[Surprising fact or statistic]."
• "I didn't expect [result]. Neither will you."

Best for: Benchmarks, experiments, data-driven articles

Type 9: Celebration

Share a win that inspires or teaches.

Patterns:

• "We just [achievement]. Here's the [number]-month journey."
• "[Project] just hit [milestone]. What we learned building it."

Best for: Launch posts, retrospectives, milestones

Type 10: Identity

Speak directly to a group's shared experience.

Patterns:

• "If you're a [role] who [shared experience], this is for you."
• "Every [role] has [this moment]. Here's how to handle it."

Best for: Career content, community content, opinion pieces

---

2. Copywriting Frameworks for Article Intros

PAS (Problem - Agitate - Solution)

The most versatile short-form framework. Name the exact pain, twist the knife on consequences, then present the solution. Rooted in loss aversion: losses feel ~2x worse than equivalent gains.

Example for a technical article intro:

• Problem: "Your Go CI benchmarks run on different CPU architectures than production."
• Agitate: "Every performance regression you catch in CI might be a false positive. Real regressions slip through to prod."
• Solution: "Here's how to detect and fix the mismatch in 10 minutes."

AIDA (Attention - Interest - Desire - Action)

Better for longer intros. Hook with something unexpected, provide context that makes the reader lean in, show the transformation, tell them what to do.

BAB (Before - After - Bridge)

Best for transformation narratives and case studies. Paint the painful current state, the desired future, then show how your content bridges the gap.

FAB (Feature - Advantage - Benefit)

Translates technical details into human value.

• Feature: "One-click rollback in the deployment pipeline"
• Advantage: "Undo bad deploys in seconds instead of minutes"
• Benefit: "Ship with confidence. No more 2am panic fixes."

PASTOR (Problem - Amplify - Story - Transformation - Offer - Response)

Extended PAS with narrative elements. Best for longer newsletter intros. Rule: 80% of the intro focuses on the transformation, only 20% on the "offer" (your article).

4 U's Headline Checklist

Rate each headline 1-4 on each dimension. Priority: Useful > Urgent > Unique > Ultra-Specific. If you can only hit 3, drop Urgency.

---

3. Headline Formulas and Data

Research-backed findings

BuzzSumo (100M articles): Optimal length 7-12 words for LinkedIn/B2B. Top list numbers: 10, 5, 15, 7. "How to..." is ~3x more shared than runner-up on LinkedIn.

Nature Human Behaviour (2023, 105K headlines, 370M impressions): Negative emotion words increase CTR. Driver is sadness, not anger or fear. Each negative word +2.3% CTR. Fear words _decrease_ clicks.

Nature Scientific Reports (2024): Inverted-U with concreteness. Too vague or too concrete both underperform. Moderate specificity (relevance signal + curiosity gap) is optimal.

Upworthy's 25-headline method: Generate 25+ variants per article, A/B test 4-5 finalists. Headlines #20-25 are often the most original (obvious options exhausted).

Proven formula templates for technical content

1. "How to [specific thing] (without [common pain])" 2. "[Number] [things] I wish I knew before [activity]" 3. "Why [popular tool/practice] is [surprising claim]" 4. "I [specific action] for [time/scale]. Here's what I found." 5. "The [adjective] guide to [topic] that [qualifier]" 6. "[Common thing] is broken. Here's how to fix it." 7. "What [impressive entity] taught me about [topic]" 8. "Stop [common practice]. Do [better practice] instead." 9. "[Topic]: the good, the bad, and the [unexpected]" 10. "A [role]'s guide to [topic] (from someone who [credibility])"

---

4. Developer-Specific Constraints

• Specificity over cleverness: Include tool, language, or framework name
• Numbers signal rigor: "3 compiler flags that reduced binary size by 40%"
• Avoid superlatives: "ultimate", "complete" trigger the BS detector
• Cognitive dissonance works: "Why our fastest service runs the slowest language"
• Honesty hooks: "What I got wrong about [topic]" signals genuine insight

---

5. Open Loop Technique

George Loewenstein's Gap Theory: curiosity happens when we feel a gap in our knowledge.

Technique:

1. Highlight what the reader already knows 2. Reveal what they're missing 3. The gap must be manageable (not too big, not too small)

In practice: open a loop in the headline or first sentence, resolve within 1-3 paragraphs, open a new loop, close all by the end. Creates reading momentum.

Copyhackers tested this: curiosity headline outperformed direct headline by 927%. But the gap must be credible, not manipulative.