How to Write a Technical Blog Post People Actually Finish

Most technical posts are not abandoned because the topic is dull. They are abandoned because the reader cannot tell, after two paragraphs, what the post is about or why they should keep going. The fix is mostly structural, and it can be learned.

This is the process I use. It works for an incident write-up, a robotics build log, a design critique or a short note on a compiler flag.

1. Pick one idea

Write the post's idea as a single sentence before you write anything else. Not a topic, an idea.

Topic: "Kubernetes autoscaling."
Idea: "Our HPA thrashed because CPU requests were set to 10% of real usage, and fixing requests mattered more than tuning the autoscaler."

If you cannot get it into one sentence, you have two posts, or you do not yet know what you think. Both are fine. Split it, or keep working on the problem until the sentence appears.

Everything that does not serve the sentence goes into a notes file for a later post. This is the hardest cut to make and the one that matters most.

2. Outline before you draft

An outline is a list of the claims the reader must accept, in order, to arrive at your idea. For the autoscaling example:

What we saw (pods scaling 3 → 40 → 3 every few minutes).
What we assumed was wrong (the HPA thresholds).
What the metrics actually showed (requests far below real usage).
The fix and the result, with numbers.
What we would check first next time.

Five or six headings is plenty for a post under 1,500 words. If the outline reads like a story with a clear turn, the draft will too.

3. Make the first paragraph do its job

The first paragraph has to answer three questions: what is this about, who is it for, and what will I get. Readers decide fast. Jakob Nielsen's classic study of web reading (1997) found that 79% of test users scanned new pages and only 16% read word by word. Your opening is the part they will definitely see.

A weak opening:

Autoscaling is an important part of modern cloud infrastructure, and many teams use it.

A stronger one:

For two weeks our checkout service scaled from 3 to 40 pods and back every few minutes. We spent most of that time tuning the autoscaler. The real problem was a single number in our resource requests.

The second version names a concrete situation, hints at a twist, and promises a specific payoff. It also does not waste a sentence on background the reader already has.

4. Show, don't tell

Claims like "this was much faster" or "the gripper was unreliable" ask the reader to trust you. Evidence lets them check.

Code: Show the smallest snippet that demonstrates the point, not the whole file. Strip unrelated config.
Output and logs: A five-line excerpt of real output beats a paragraph describing it.
Diagrams: One box-and-arrow sketch of the data flow often replaces three paragraphs. Hand-drawn is fine if it is legible.
Photos: For hardware, a photo of the actual bench setup, the scope trace or the failed part is often the most convincing thing in the post.
Numbers: "p95 latency dropped from 840 ms to 210 ms" is a claim someone can reason about. "Way faster" is not.

The editor on this site supports Markdown and image upload. You can paste a screenshot straight from your clipboard or drag an image file into the editor, and it will be uploaded and inserted for you. Use fenced code blocks with a language tag so code is highlighted.

Every image needs alt text that says what the image shows and why it matters, not "screenshot.png". The W3C's alt decision tree is a quick way to decide what to write.

5. Cite your sources

If a claim comes from somewhere else, link to it. That includes standards, papers, vendor docs, other people's blog posts and your own earlier posts.

Good citation habits:

Link to the primary source, not a summary of a summary.
Note the version or date when it matters ("as of Kubernetes 1.30").
Quote briefly and accurately. If you paraphrase, make sure the source actually says what you claim.
If you used an AI assistant to research, verify each fact against the original source before publishing. A confident wrong citation does more damage than no citation at all.

Inline links where the claim appears, plus a short source list at the end, work well for technical posts.

6. Edit in passes

Do not try to fix everything at once. Each pass looks for one kind of problem.

Pass 1, structure. Does every section serve the one-sentence idea? Is anything in the wrong order? Cut whole sections here, before you polish sentences you will delete anyway.

Pass 2, clarity. Read it as someone one level less experienced than you. Define acronyms on first use. Replace vague words with numbers. Paul Graham's case for plain language in Write Simply (2021) is worth reading here: "the easier something is to read, the more deeply readers will engage with it."

Pass 3, cutting. George Orwell's rules from Politics and the English Language (1946) still hold: never use a long word where a short one will do, and if it is possible to cut a word out, always cut it out. Look especially for throat-clearing at the start of paragraphs ("It is worth mentioning that...").

Pass 4, checking. Run every code sample. Click every link. Confirm every number against your notes.

Pass 5, out loud. Read the post aloud, or at least the opening and closing. Awkward sentences become obvious when you hear them.

Sleep on it between pass 1 and pass 5 if you can. Distance is the cheapest editing tool there is.

7. Write the title last

A good technical title tells the reader what they will learn, specifically enough that the right people click and the wrong people do not.

Weak	Better
Thoughts on autoscaling	Why our autoscaler thrashed (and it wasn't the autoscaler)
My robot arm project	Calibrating a 6-DOF arm with a $30 webcam and AprilTags
Security lessons	Triaging 4,000 alerts a day: what we stopped looking at

Avoid clickbait you cannot pay off. If the title promises a surprise, the post must deliver one in the first few paragraphs.

A short checklist before you publish

The idea fits in one sentence, and the first paragraph makes it clear.
Every section serves that idea.
There is at least one piece of concrete evidence: code, output, a diagram or a photo.
Images have alt text.
Every factual claim is linked or clearly marked as your own observation.
Code runs, links work, numbers match.
The title says what the reader will learn.

Then publish it. A post that is 90% good and online helps more people than a perfect draft that never ships.

Sources

How Users Read on the Web, Jakob Nielsen (NN/g) — 1997 study: 79% of users scanned, 16% read word by word.
Write Simply, Paul Graham — March 2021 essay on why plain writing gets read more deeply.
Politics and the English Language, George Orwell — 1946 essay with the six rules for clear prose.
An alt Decision Tree, W3C WAI — practical guide to writing alt text for images.