SEO for Technical Articles¶

How to optimize technical articles for search without degrading quality. SEO for technical content differs from marketing SEO - the audience searches for specific error messages, tool names, and "how to" queries. Keyword stuffing and clickbait actively hurt credibility.

Title Optimization¶

The title is the highest-impact SEO element. It appears in search results, social shares, and RSS feeds.

Structure: [Specific outcome] with [specific tool/method] or [Problem] [Solution approach]

Good titles: - "Reducing Docker Build Times from 15 Minutes to 30 Seconds with Multi-Stage Builds" - "Why Our PostgreSQL Queries Slowed Down After Upgrading to v16" - "Implementing RAG with pgvector: Lessons from 1M Documents"

Bad titles: - "A Comprehensive Guide to Docker Optimization" (vague, AI-sounding) - "Docker Tips and Tricks" (too generic, high competition) - "You Won't Believe How Fast Our Builds Got" (clickbait) - "Understanding Modern Containerization Practices" (no specificity)

Rules: - Include the primary keyword naturally (tool name, technology, problem) - Keep under 60 characters for full display in Google results - Front-load the important words (Google truncates from the right) - Use numbers when genuine ("15 Minutes to 30 Seconds" not "10 Tips for")

Meta Description¶

The description appears under the title in search results. 150-160 characters.

Good:

We cut Docker build times by 97% using multi-stage builds, BuildKit caching, and a custom base image. Here's the exact Dockerfile changes that worked.

Bad:

This comprehensive guide explores Docker optimization techniques that can help you improve your build times and enhance your development workflow.

The good version: specific numbers, specific techniques, promise of exact code. The bad version: could describe any Docker article ever written.

Header Structure (H1-H3)¶

Headers serve dual purpose: reader navigation and search engine topic signals.

# Primary Topic (H1 - one per page, matches title)

## Major Section (H2 - 4-7 per article)
Main structural divisions. Each should be independently useful.

### Subsection (H3 - 2-4 per H2)
Details within a section. Don't go deeper than H3 in articles.

Each H2 should be a plausible search query. Someone might search "docker multi-stage build example" - make that an H2.

Don't use headers for emphasis. "Important Note" as an H3 wastes a ranking signal.

URL Structure¶

• Kebab-case: /reducing-docker-build-times not /Reducing_Docker_Build_Times
• Short and descriptive: 3-5 words in the slug
• Include primary keyword: /docker-build-optimization not /post-2024-03-15
• No dates in URL unless the content is time-bound (news, release notes)
• Permanent: changing URLs breaks backlinks and search ranking

Internal and External Links¶

Internal links (to your other articles): - Link from high-traffic pages to new content - Use descriptive anchor text: "our Docker caching guide" not "click here" - 3-5 internal links per article is optimal - Cross-reference related articles in "See Also" sections

External links: - Link to official docs, GitHub repos, papers (signals credibility) - Don't link to competitors' blog posts for the same topic - Use rel="nofollow" for user-generated content or untrusted sources - Check links every 6 months - broken links hurt ranking

Keyword Strategy for Technical Content¶

Technical content keywords are different from commercial keywords:

Finding keywords: - Google autocomplete: type your topic and see suggestions - "People also ask" boxes in search results - Stack Overflow question titles for your technology - GitHub issue titles and discussions - Search Console data for existing content (what queries already bring traffic)

Do NOT: - Stuff keywords unnaturally ("Docker Docker build Docker optimization Docker cache") - Target broad keywords ("programming tutorial") - too competitive, too vague - Ignore long-tail queries - "docker multi-stage build python poetry" has less traffic but higher conversion

Image SEO¶

• Alt text: describe what the image shows, include keyword naturally. "Docker multi-stage build diagram showing three stages" not "image1.png"
• File names: docker-multistage-diagram.png not Screenshot 2024-03-15.png
• Compression: use WebP format, keep under 200KB for diagrams, under 500KB for screenshots
• Diagrams > screenshots: search engines can't read code in screenshots. Include code as text blocks AND as screenshots if visual context matters.

Technical SEO for Blog Platforms¶

Hashnode / Hugo / Astro¶

• Set canonical_url in frontmatter
• Configure sitemap.xml generation
• Add structured data (Article schema) for rich snippets
• Enable RSS feed

Cross-posting SEO¶

# dev.to frontmatter
canonical_url: https://yourdomain.com/docker-build-optimization

Measuring Impact¶

Key metrics: - Organic traffic (Google Search Console) - clicks from search, not social - Average position for target keywords - Click-through rate - if position is good but CTR is low, improve the title - Backlinks (Ahrefs/SEMrush free tier) - other sites linking to your article - Time on page - if high traffic but low time, the content doesn't match the search intent

Timeline: SEO results take 2-6 months. Don't judge an article's search performance in the first week - social traffic comes first, search traffic builds slowly.

Content Freshness¶

Google rewards updated content for queries with time-sensitivity: - Add "Updated YYYY-MM" to articles with version-specific content - Revisit top-performing articles every 6-12 months - Update code examples when major versions release - Don't change URLs when updating - add/edit content in place

Gotchas¶

• Issue: Optimizing for SEO keywords makes titles and headers sound generic and AI-like ("Comprehensive Guide to Docker Optimization"). Fix: Optimize for specificity instead of keyword volume. "Cutting Docker Builds from 15min to 30s" is better SEO and better writing than "Docker Build Optimization Guide" because it's more likely to match what someone actually searches.
• Issue: Writing separate articles for every keyword variation ("docker cache," "docker layer caching," "docker build cache") creates thin content that cannibalizes itself. Fix: Write one thorough article that covers the topic comprehensively. Use keyword variations naturally as H2/H3 headers within that article.
• Issue: Chasing trending keywords leads to writing about topics you have no genuine experience with, producing shallow AI-detectable content. Fix: Write about what you actually built/debugged/measured. The specificity of real experience is better SEO than any keyword strategy.

See Also¶

• publishing platforms
• technical article structure
• editing checklist