The two writing modes that actually matter for technical posts

I have published sixteen posts on this site. Looking back at them, they split cleanly into two kinds, and when I get the kind wrong I can feel the post dragging before I hit publish. One kind walks the reader through a thing I built, in order, with enough code to reproduce it. The other kind reflects on a thing I learned, without necessarily showing the artifact. Each needs a different draft process. Here's how I tell them apart and write them differently.

The walk-through post

The purpose of a walk-through post is simple: the reader leaves able to build a thing. They should be able to follow your steps, copy your code, and have a working artifact at the end. It is a tutorial, a guide, a map from A to B.

Most of my popular posts fall into this category. Posts like "The 200-line agent loop that does everything OpenAgents does" or "The agent-ready web checklist: 23 things every indie site should ship" are pure walk-throughs. Even a more opinionated piece like "Cloudflare's agent-ready browser is a Trojan horse" is structured as a walk-through of my reasoning, grounded in a technical artifact I built to prove the point.

The shape of these posts is almost always the same. I open with a clear statement of the thing I built and the claim I am making about it. Then, each section corresponds to a logical step in the construction. Code blocks are essential, and they must be annotated. The reader needs to know not just what the code is, but why it is that way. The post closes by showing the final result, often with a screenshot or a link to it in production.

The biggest risk with a walk-through is that it becomes boring. A step-by-step guide can easily turn into a dry recitation of commands. The mitigation is to lead with a strong, counterintuitive claim. Your intro needs to hook the reader by promising a surprising outcome. For my agent loop post, the claim was, "Agent frameworks are 5000 lines because nobody read the spec, not because the problem is hard." That gives the reader a reason to care about the 200 lines of code that follow.

When editing a walk-through, the rule is to cut everything that is not about the artifact. Save your philosophy for another day. Every sentence should help the reader build the thing. If it doesn't, it's noise.

The reflection post

The purpose of a reflection post is different. The reader leaves thinking differently about something they already know. You are not giving them a new skill; you are giving them a new lens. It is an essay, an observation, a provocation.

My posts on "Building for one reader" and "Why my agent runs on a Mac mini" are reflections. So was the short piece on "Writing without em-dashes". These posts are about a process, a principle, or a personal choice. They argue a point of view, using my own experience as the primary evidence.

The shape of a reflection is more fluid, but it generally follows an argumentative structure. It might start with a personal vignette or a bold claim. From there, it builds an argument, often by considering and refuting a counter-argument. It closes not with a finished product, but with a settled stance. The goal is to persuade, not to instruct.

The main risk of a reflection post is waffle. Without the concrete structure of a build process, it is easy to drift into abstraction and vague pronouncements. The mitigation is to be ruthless about grounding every paragraph. Force each one to earn its place with a specific image, a hard number, or a direct quote. If a paragraph is just a cloud of concepts, it needs to be rewritten or deleted.

The most important cut for a reflection post is the code block. Reflection posts almost never need code. If you find yourself reaching for a code snippet to illustrate a point, you might be writing the wrong kind of post. The evidence should be in the reasoning, not the implementation.

The sign: what does your draft want to be?

Sometimes a post starts without a clear identity. The first draft is a messy hybrid of tutorial and essay. That is fine. The key is to diagnose what the post wants to be during the editing process and then commit to that form.

I use two questions to make the diagnosis.

First: is my reader more likely to quote me, or quote my code? If they are going to copy and paste a line of prose into their team's Slack, it is a reflection. If they are going to copy and paste a block of code into their editor, it is a walk-through. You cannot optimize for both.

Second: does my first draft want to show something, or argue something? A draft that is full of // Step 1: Configure the database comments wants to be a walk-through. A draft that is full of "On the one hand... but on the other hand..." transitions wants to be a reflection. Listen to the language your subconscious is already using.

If a post truly wants to do both, it should become two posts. Write the walk-through first. Build the thing and show others how. Then, a week later, write the reflection. Step back and explain the philosophy behind what you built. Trying to cram both into a single article makes it a confusing mess.

The failure mode I still hit

My most common mistake is writing a reflection post that is littered with unnecessary code blocks. I do this because I am insecure. The code blocks are not there to serve the argument. They are there to signal "I am a technical person writing a technical blog". They are a form of credentialing.

The result is a post that is longer, slower, and less effective. The reader who came for the reflection gets bogged down in implementation details they do not care about. They start to skim. The argument loses its momentum. The post fails.

My fix for this is mechanical and unforgiving. In the second draft of any post that feels like a reflection, I delete every single code block. Then I reread the post. If the argument still makes sense, if the post still achieves its goal, then the code blocks were decoration. They stay deleted.

There is a rare counter-example. A single code block can be acceptable in a reflection if it is the central exhibit of the post. The code itself becomes the image, the specific detail that the entire argument hinges on. But this is an exception. If you have more than one, you are probably in the failure mode.

Openings that work for each kind

The first hundred words determine which kind of reader you will attract. You have to signal the post's mode immediately.

A walk-through opening should be brutally direct. "Here's the thing. Here's the claim. Here's how I built it. Let's go." There is no room for throat-clearing. The reader is here to accomplish a task, and your job is to get them started as quickly as possible. State the destination and start drawing the map.

A reflection opening works the opposite way. It starts small and specific to earn the right to become abstract. It uses a concrete anchor: a specific image, a name, a date, a constraint. My post on building for one reader starts, "I have one imaginary reader in my head. Her name is Ana." This grounds the abstract concept of a "target audience" in something tangible. The reader is intrigued, not intimidated.

Endings that work for each kind

How you end the post solidifies its purpose. The reader should leave with a clear takeaway that matches the mode of the piece.

A walk-through ending should be a single, punchy claim about the significance of the artifact. It is the final "ta-da". After walking the reader through 200 lines of code, the ending can be as simple as: "212 lines. One SQLite file. No framework needed." It summarizes the value proposition of the entire tutorial in a memorable, satisfying way.

A reflection ending is quieter. It should offer one sentence that the reader might screenshot and think about later. This is not about being quippy or clever. It is about being earned. After hundreds of words of argument and evidence, you should be able to state your final position with clarity and weight. The sentence should feel like the inevitable conclusion of the entire piece.

The meta trap

This post is a meta-post. It is writing about writing. This is a dangerous genre. It is easy to get stuck writing meta-posts indefinitely because they feel productive, but they can become a substitute for doing the actual work.

They get diminishing returns. Your first meta-post is useful because it forces you to clarify your own process. Your fifth is probably navel-gazing. I try to limit myself. I write one meta-post like this for every 12 to 20 regular posts. No more.

Here is a simple diagnostic. If the last three posts in your feed are all about your process, you have a problem. You are polishing the engine instead of driving the car. Close the editor. Go build something. Then come back and write about that.

The split is simple once you see it. Walk-throughs serve builders. Reflections serve readers. Most posts fail because they try to be both, and end up being neither. Pick one. Commit to it. And cut everything that belongs to the other.