These are things I'm practising, not claiming mastery of. If you read a post of mine and found it dull, that's feedback I want.
Still, after writing technical posts for my own site and this series, a few patterns stand out. This post is a field guide to the structure I aim for, a pre-publish checklist, and the mistakes I try to avoid.
Start with the reader's question
Every post answers a question someone has, even if they haven't typed it. Before writing, finish this sentence:
After reading this, you'll be able to ______.
If you can't, the post doesn't have a purpose yet. "Understand RAG" is vague. "Explain chunking and retrieval well enough to build a five-note prototype" is concrete.
The title is a promise
Good titles are specific and honest:
- Vague: Thoughts on databases
- Better: I put my business rules in the database instead of React, here's what it bought me
The second tells you the topic, a decision, and a payoff. But don't overpromise. A title that claims more than the post delivers loses trust faster than a dull title loses clicks.
The first paragraph earns the second
No throat-clearing. Skip "In today's fast-paced world of software development…". Start with the problem, a surprise, or a sentence that sets the stakes:
- "When something breaks, my worst instinct is to start changing things."
- "My site's deploys silently failed for two weeks."
If a stranger can't tell why to keep reading after three sentences, cut until they can.
One idea per post
If a post has three big ideas, it's three posts. Readers finish things with a clear spine. Everything that doesn't serve the spine goes into another post or gets cut.
Use structure, then trust it
For technical writing, I use a repeating shape:
- The problem in human terms.
- The idea in one or two sentences.
- A concrete example, with code if code helps.
- What went wrong or what it costs.
- A takeaway you can reuse.
- A question for the reader.
Subheadings make it scannable, since most readers skim first and read second. Make each heading say something, not just "Overview".
Show, don't just tell
- Code people can copy is the most useful thing in a technical post, so make it runnable or clearly mark it as a sketch.
- Tables work for comparisons.
- A diagram or a summary image helps visual readers and gives your post a shareable image.
- Real numbers and real names, when they're true and checkable.
Keep the honesty rule
For this series, I follow rules I wrote on Day 1: only write what I did or believe, say what didn't work, and label opinions as opinions. Practically that means:
- No invented statistics.
- No "everyone knows".
- If I didn't measure it, I don't say it's fast.
- Limits are part of the post, not hidden at the bottom.
Honest writing also happens to be easier to write: you never have to remember which story you made up.
An honest ending
End on something useful:
- A limit: "here's what this doesn't cover."
- A question: something you genuinely want answered.
- A next step: what you'd try, or what comes next.
Avoid ending on a summary of what you've just said, unless the post is long enough that readers need it.
A pre-publish checklist
- [ ] Can I finish the sentence "you'll be able to…"?
- [ ] Does the title match what the post delivers?
- [ ] Do the first three sentences give a reason to continue?
- [ ] One idea only?
- [ ] Is every claim something I can back up?
- [ ] Code tested or labelled as a sketch?
- [ ] Headings that say something?
- [ ] An ending that gives something back?
- [ ] Spelling and links checked?
The read-aloud test
Read the post aloud. Wherever you stumble, the reader will too. Long sentences you run out of breath on need splitting. Words you wouldn't say to a friend need replacing.
Reading time
There's a trade-off between depth and attention. On my own site, reading time is computed from the word count so I don't hand-write it. A rough rule: 200 words a minute, so a 1,500-word post is about seven minutes. Long is fine if every section earns its place. Cut anything that's there to hit a length.
What I'm still learning
- Cutting my own favourite paragraph when it doesn't serve the post.
- Writing a title after the draft, when I know what it really says.
- Resisting the urge to sound more expert than I am.
A before/after: rewriting an intro
Before (a typical first draft):
In the modern world of software development, testing is becoming more and more important. Many developers know they should write tests, but it can be hard to find the time. In this post I will talk about my experience with testing and how I plan to improve it.
It's polite and says almost nothing. Nothing happens in the first three sentences.
After:
Writing tests is advice I give and haven't followed everywhere. CardBridge has no automated test suite. So here's the plan, publicly, so I'm accountable.
Same topic. The second version admits something specific, sets a stake and gives a reason to continue. It's also shorter.
A four-round editing pass
Don't edit everything at once. Do it in rounds.
Round 1: Structure. Does the post have one idea? Are the sections in the right order? Cut or move whole sections.
Round 2: Clarity. Rewrite sentences that you had to read twice. Replace jargon with plain words, or define it.
Round 3: Evidence. For each claim, ask: can I back this up? Add the command, link or example. Delete what you can't.
Round 4: Polish. Spelling, links, code formatting, headings, alt text.
Taking a break of even a few hours between round 3 and round 4 makes errors much easier to see.
Words to cut
These add length but not meaning:
- "very", "really", "quite", "basically", "actually"
- "In order to" (use "to")
- "It is important to note that" (just note it)
- "There are many X that Y" (name two)
- "Needless to say" (then don't)
Sentences that earn their place
Prefer concrete over abstract:
| Vague | Concrete |
|---|---|
| "Performance improved." | "The query went from a full scan to an index lookup." (only if true) |
| "It was a challenging bug." | "It only failed for viewers, never for editors." |
| "I learned a lot." | "I learned that a postinstall script can be skipped by the host." |
If you didn't measure a number, don't print one.
Formatting for skimmers
Many readers skim first. Help them:
- Headings that carry information.
- Short paragraphs, three or four lines.
- Lists for parallel items, tables for comparisons.
- Code blocks with a language tag.
- Bold for the one phrase per section you'd want a skimmer to see.
- An image or summary card to break up long text.
Don't overuse bold; if everything is emphasised, nothing is.
Titles: some patterns
| Pattern | Example |
|---|---|
| The honest admission | "My site's deploys silently failed for two weeks. I didn't notice" |
| The decision and payoff | "I put my business rules in the database instead of React, here's what it bought me" |
| The plain how-to | "Row Level Security explained with one tiny example" |
| The comparison | "Learning in public vs learning in private: the trade-offs" |
Write five titles, then pick the one that's most specific and true.
Getting feedback before publishing
Send the draft to one person and ask three questions:
- Where did you get bored?
- Where did you get lost?
- What's the one thing you remember?
If their answer to the third isn't your main point, the post isn't clear yet.
A habit: keep a "stuff" file
Keep a note of small things you learn and the questions people ask you. Most good posts begin as a note that kept growing.
What's one post you read recently that you couldn't stop reading? What made it work?
☕ Enjoyed this post? You can support my writing on Ko-fi.
