Technical Article Structure¶

★★★★★ Basic

How to structure technical articles that get read, shared, and bookmarked. Based on patterns from high-engagement technical content across platforms. The core principle: lead with the problem you actually had, not a topic overview.

The Hook-Problem-Solution Pattern¶

The highest-performing structure for technical articles:

Hook (1-3 sentences) - the specific situation that made you write this
Context - what you were trying to do and why existing solutions didn't work
Solution - what you did, with code and specifics
Results - what happened, with numbers
Caveats - what doesn't work, edge cases, limitations
Next steps - what you'd do differently or what's left to explore

This is NOT the standard "Introduction -> Background -> Method -> Conclusion" academic structure. Technical blog readers want the payoff early and details later.

Opening Patterns That Work¶

Lead with the problem:

Our CI pipeline took 47 minutes. Deploys happened twice a day, which meant engineers spent 90+ minutes daily waiting for builds.

Lead with a surprising result:

We deleted 60% of our microservices and reliability improved. Here's why.

Lead with a failure:

I mass-migrated 2M rows to the new schema on Friday at 4pm. The rollback took until Sunday.

What doesn't work:

In today's fast-paced world of software development, continuous integration and continuous deployment (CI/CD) have become essential practices for modern engineering teams. This article explores...

Code Examples Placement¶

Rules: - First code example within the first 1/3 of the article - Use code from your actual project, not generic examples - Include version numbers, OS, and runtime details - Show the error/output, not just the input - Keep individual code blocks under 30 lines - split longer examples

Good placement pattern:

[2-3 paragraphs of context]
[code block showing the problem]
[1-2 paragraphs explaining]
[code block showing the solution]
[paragraph on results]
[code block showing results/benchmarks]

Bad placement pattern:

[10 paragraphs of theory]
[massive code block with everything]
[brief conclusion]

Section Breakdown¶

For Tutorial/How-To Articles¶

# [Specific outcome] with [specific tool]

## The Problem
[2-3 sentences - what wasn't working]
[Error message or screenshot]

## What I Tried First
[Brief dead-end descriptions - shows real experience]

## The Solution
[Step-by-step with code blocks]
[Each step: what to do, why, expected output]

## Gotchas
[Things that broke during implementation]
[Edge cases discovered in production]

## Results
[Before/after metrics]
[Timeline: how long the migration/implementation took]

For Investigation/Debug Articles¶

# How We Fixed [specific problem]

## Symptoms
[What was observed - exact error messages, metrics]

## Initial Hypotheses
[What we thought was wrong and why]

## Investigation
[Tools used, commands run, what each revealed]
[Include dead ends - "we checked X but it was fine"]

## Root Cause
[What actually happened]

## Fix
[What we changed, with code diff]

## Prevention
[What we changed to catch this earlier]

For Comparison/Evaluation Articles¶

# [Tool A] vs [Tool B] for [specific use case]

## Our Requirements
[Specific criteria, not generic "performance and scalability"]

## Test Setup
[Exact versions, hardware, dataset size]

## Results
[Table with numbers]
[One section per criterion with details]

## Our Choice
[What we picked and why - take a position]

## What We'd Choose Differently For
[Other use cases where the other tool wins]

Optimal Length¶

Sweet spot: 1200-2000 words (7-10 minute read)
Short articles (<5 min): high completion rate but less engagement
Medium articles (5-10 min): best balance of completion and depth
Long articles (10+ min): lower completion, higher bookmarks
"Evergreen" tutorials get steady long-term traffic regardless of length

Formatting Essentials¶

Headers: H2 for major sections, H3 for subsections. No H4+ in blog posts
Code blocks: always language-tagged, < 30 lines each
Images/diagrams: every 300-500 words for engagement
Bold for key terms on first use, not for emphasis in every paragraph
Links: to specific relevant resources, not "read more about X here"
TL;DR: at the top for long articles, not at the bottom

Techniques for Authenticity¶

From analysis of highest-rated technical articles:

Include dead ends - "I tried X but it failed because..."
Show specific error messages, stack traces, version numbers
Use your actual numbers - "took 47 minutes on my M1 MacBook"
Reference specific tools by version - not "a popular framework"
Disagree with something - take a stance on a tool or approach
Admit what you don't understand - "I still don't know why this works"
Use code from your actual project, not sanitized examples
Mention time - "at 2am I realized the problem was..."
Include screenshots of your actual terminal/IDE
Show the before/after - concrete proof the solution works

Anti-Patterns¶

Starting with "In today's world..." or "X has become increasingly important"
Explaining basics your audience already knows (know your reader's level)
Equal space to every section regardless of value
No code until the second half of the article
Generic conclusion restating the introduction
"I hope this was helpful" as a closing

Gotchas¶

Issue: Structuring a debug story chronologically ("first I checked A, then B, then C") can be tedious if A and B were dead ends. Fix: Lead with the root cause and fix, then explain the investigation. Readers want the answer first, the journey second.
Issue: Including every detail about the setup makes the article inaccessible to readers with different environments. Fix: State your exact environment (OS, versions, hardware) once at the top, then focus on the concepts. Link to setup guides rather than embedding them.
Issue: Code examples that work in isolation but not in real projects because imports, configuration, and error handling are omitted. Fix: Show complete, runnable code for at least one key example. Mark simplified examples explicitly: "// simplified - see full version at [link]."