Scrolls
5 min read
On this page

Structure for Practitioners

Technical blog posts are not essays. Your reader is a developer who has a problem, found your post in a search engine, and will leave in 30 seconds if you do not prove this post solves their problem. Every structural choice should serve that reader. Hook them with the problem, give them context fast, deliver the solution with code, acknowledge trade-offs honestly, and point them to what comes next. Skip the filler. Get to the point.

The Five-Part Structure

This structure works for the vast majority of technical blog posts. It is not the only structure, but it is the default you should deviate from intentionally rather than accidentally.

1. Hook       — What problem does this solve?
2. Context    — Why does it matter? What do you need to know first?
3. Solution   — The actual answer, with code
4. Trade-offs — What you gave up, what could go wrong
5. Conclusion — What to do next

Each section has a specific job. If a section is not doing its job, cut it or fix it.

The Hook

The hook is your first paragraph. It answers one question: "Should I keep reading?" You have roughly two sentences to convince the reader that this post addresses their problem.

Bad hook:
  "In this blog post, I will discuss some strategies for handling
   database migrations in a microservices architecture. Migrations
   are an important topic that many developers need to understand."

Good hook:
  "If you run database migrations in a microservices architecture
   the same way you run them in a monolith, you will eventually
   corrupt data or cause downtime. Here is the pattern we use to
   avoid both."

The bad hook tells the reader what you plan to do. The good hook tells the reader what they will gain. The difference is perspective: stop talking about yourself and start talking about the reader's problem.

Hook Patterns That Work

Problem statement:
  "Kubernetes health checks have three modes, and using the wrong
   one will cause cascading failures under load."

Surprising result:
  "Switching from JSON to Protocol Buffers cut our API latency
   by 40% — but only after we fixed the serialization layer."

Common mistake:
  "Most teams configure their connection pools wrong. Here is how
   to tell if yours is one of them."

Direct promise:
  "This post will show you how to set up end-to-end type safety
   from your database schema to your React components."

Notice what all of these skip: "In this post I will...", "Hello and welcome to my blog...", "Before we begin, let me introduce myself...". Delete all of that. The reader does not care who you are until after your post has helped them.

Context

Context is the minimum background the reader needs to understand the solution. It is not a literature review. It is not a history lesson. It is the setup for the punchline.

Ask yourself: what does the reader need to know to understand my solution, and what can I link to instead of explaining?

Too much context:
  "REST was first described by Roy Fielding in his 2000 doctoral
   dissertation. It stands for Representational State Transfer.
   There are six architectural constraints..."

  [Three paragraphs later, you still haven't gotten to the point]

Right amount of context:
  "Our API uses REST with JSON responses. We needed to add
   pagination to an endpoint that returns up to 50,000 records.
   The naive approach — loading everything and slicing — was
   causing OOM errors in production."

When Context Needs Code

If your solution builds on a specific setup, show that setup as code. Do not describe it in prose.

Instead of:
  "We have a Node.js application that uses Express for routing
   and connects to a PostgreSQL database using the pg library."

Write:
  "Here is the starting point — a standard Express app with a
   Postgres connection:"

  // server.js
  const express = require('express');
  const { Pool } = require('pg');

  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const app = express();

Code is context. Show it early. The reader can skim code faster than they can parse a paragraph describing code.

The Solution

This is the core of your post. It is the reason the reader is here. Two rules: show code, and explain the non-obvious parts.

Show Code Early

Do not build up to the code through paragraphs of explanation. Show the code first, then explain it. Developers read code faster than prose. Give them the code, then use prose to explain what is not self-evident.

Bad ordering:
  "First, we need to create a middleware function that intercepts
   the request before it reaches the handler. This middleware will
   check the Authorization header, extract the JWT token, verify
   it against our signing key, and attach the decoded payload to
   the request object. Here is how that looks:"

   [code block]

Good ordering:
  "Here is the auth middleware:"

   [code block]

  "The non-obvious part is line 12: we verify against the JWKS
   endpoint rather than a static secret. This lets us rotate keys
   without redeploying."

The first approach makes the reader hold the entire algorithm in their head while reading prose, then cross-reference against code. The second approach lets the reader see the whole picture, then zoom into the interesting parts.

Annotate, Do Not Narrate

Do not describe what every line of code does. The reader can read code. Focus on:

  • Why you made a specific choice
  • What is surprising or non-obvious
  • Where the gotchas are
  • What would break if you changed something
Unhelpful annotation:
  "Line 1 imports the http module. Line 2 creates a new server.
   Line 3 sets the port to 3000."

Helpful annotation:
  "We set the timeout on line 8 to 30 seconds, not the default 120.
   With the default, a slow upstream service causes connections to
   pile up and eventually exhausts the connection pool."

Use Complete, Runnable Examples

Nothing is more frustrating than a code example that does not work when you copy it. Include imports. Include setup. Include the command to run it.

Incomplete example:
  const result = await transform(data, options);

Complete example:
  // transform.js
  const { transform } = require('./lib/transform');

  const data = { name: 'test', values: [1, 2, 3] };
  const options = { format: 'csv', header: true };

  const result = await transform(data, options);
  console.log(result);

  // Run: node transform.js
  // Output: "name,values\ntest,\"1,2,3\""

Trade-Offs

This section separates good technical writing from marketing. Every solution has costs. Acknowledging them builds trust and helps the reader decide if your approach fits their situation.

Trade-off categories to consider:

  Performance  — "This adds ~5ms per request due to the extra lookup"
  Complexity   — "You now need to manage a Redis instance"
  Portability  — "This only works with PostgreSQL 14+"
  Maintenance  — "You'll need to update the schema mapping when adding fields"
  Scale limits — "This works for up to ~10k records; beyond that, use X"

How to Write Trade-Offs

Be specific. "There are some performance implications" is useless. "This adds a network round-trip per request, which added 3-8ms in our benchmarks" is useful.

Vague trade-off:
  "Keep in mind that this approach may not be suitable for all
   situations and could have performance implications."

Specific trade-off:
  "This approach queries the permissions table on every request.
   For our app (200 RPS), the added latency was negligible — about
   2ms per request. If you are handling 10,000+ RPS, you will want
   to cache permissions in Redis or in-memory with a TTL."

When You Do Not Know the Trade-Offs

Say so. "I have been using this pattern for three months in a low-traffic application. I have not tested it under heavy load." That is more helpful than pretending there are no trade-offs.

The Conclusion

The conclusion is short. It does three things:

  1. Restates the problem and solution in one sentence
  2. Points the reader to a next step
  3. Invites feedback or questions
Good conclusion:
  "Cursor-based pagination solved our OOM issues and actually
   simplified the client code. If you are paginating over large
   datasets with PostgreSQL, the approach described above should
   work for most OLTP workloads.

   If you are dealing with full-text search results, the approach
   is different — I'll cover that in a follow-up post.

   Have a question or spot an error? Open an issue on the blog's
   GitHub repo."

What the conclusion should not do: summarize the entire post, add new information, or repeat the introduction.

Variations on the Structure

The five-part structure is the default. Common variations include tutorials (what you will build, prerequisites, steps, result, next steps), comparisons (decision, criteria, evaluation, choice, when to choose differently), and debugging stories (symptom, wrong hypothesis, investigation, root cause, fix, prevention). All follow the same principle: problem first, solution second, trade-offs third.

Formatting for Skimmability

Most readers skim. Design your post for skimming, not for linear reading.

Formatting rules:

  - Use headings every 3-5 paragraphs
  - Bold the first sentence of key paragraphs
  - Use code blocks for anything that is code, config, or CLI output
  - Use bullet lists for sets of items
  - Keep paragraphs under 5 sentences
  - Use whitespace generously

A wall of text tells the reader "this will be hard to extract information from." Structured text with headings and code blocks tells the reader "you can find what you need quickly."

Common Pitfalls

  • Starting with "In this post I will..." The reader does not care what you plan to do. Show them the problem.
  • Burying the code below paragraphs of explanation. Show code early. Explain after.
  • Incomplete code examples. Missing imports, missing setup, no way to run the code. Include everything needed to reproduce.
  • No trade-offs section. Every approach has costs. Pretending otherwise reduces your credibility.
  • Conclusions that summarize the entire post. The reader just read the post. Summarizing it again wastes their time.
  • Walls of text without headings or code blocks. Format for skimmers. They are the majority of your audience.
  • Writing long introductions about why the topic matters. If the reader searched for it, they already know it matters. Get to the solution.

Key Takeaways

  • Structure every post around the reader's problem, not your knowledge.
  • Hook with the problem in the first two sentences. Skip self-introductions.
  • Show code early and annotate only the non-obvious parts.
  • Include trade-offs. Being honest about costs builds more trust than pretending there are none.
  • Keep conclusions short: restate the solution, point to a next step, invite feedback.
  • Format for skimming. Headings, code blocks, short paragraphs, bullet lists.