AWS Builder Center
How to Write Compelling Technical Blogs

How to Write Compelling Technical Blogs

This blog walks through patterns compelling technical posts include, including story framing, stated assumptions, real world scenarios, step by step walk throughs and showing claims instead of asserting them.

Developer Experience Engineer

Intro

Most technical writers spend a lot of time writing a blog full of complex technical topics and jargon but lose their readers before the third paragraph.

This is because many technical writers focus so much on technical accuracy, that they end up only writing from their perspective and forget to put themselves in the shoes of the reader. They forget to answer the million dollar question a reader is asking:
"Why should I spend my time reading this?"
Your audience has a very short attention span and unfortunately, fewer and fewer people are compelled to read these days (OPEN THE SCHOOLS!). So you need to write with this reality in mind.

Having read a lot of compelling technical blogs, I've noticed they tend to follow recognizable patterns and incorporate similar elements. Some I've noted and incorporate into my writing include:
  • Begins with a subject the writer genuinely cares about
  • Subject is written as a story rather than technical documentation
  • Assumptions of the reader are stated early
  • Incorporates different real world scenarios
  • Demonstrates claims instead of just stating them
  • Utilizes images, videos, gifs and other forms of communication

In this article, I'll walk through these patterns and focus on what each component does and how they reinforce one another. I'll also try to apply them throughout, so you can observe each technique in the same section where I describe it.

Part 1. Choosing a Subject You Find Compelling

The first decision a writer makes is what to write about, but many go about selecting that the wrong way. Their instinct is to select a topic they expect to perform well rather than a subject they are actually excited to talk about.

Enthusiasm is one component of writing that cannot be manufactured. A reader detects its absence within the first couple paragraphs, so it just reads as a flat encyclopedia voice where even though the information is factual, it doesn't appeal to them in any way.

The alternative is to write on whatever is compelling to you. Even if the subject has already been covered, the fact that you have a personal stake of passion in the topic will show in the writing and immediately differentiate you from others. That's why your most compelling blogs tend to come from your most recent experiences.

A subject learned last week will most likely produce better writing than a subject mastered five years ago. Deep familiarity removes access to what unfamiliarity felt like, which is why it's very easy for experienced engineers to produce less followable tutorials. However, a newbie learning for the first time tends to be able to convey their experience in a very captivating way.

A writer who solved a problem recently still vividly remembers the details of their experience. That memory and the emotions behind it tend to fade away as time goes on.

Part 2. Framing the Subject as a Story

Most technical blogs openings are just definitions:
"Amazon S3 is an object storage service that offers industry leading scalability."
But that's a sentence a reader will never willingly read in an intro, because it contains no stakes, no personality and no reason to occupy the top of a page.

Consider an alternative opening:
A $400 bill hit your email for a static website that served two hundred visitors.
Take a moment to process what you felt when you read each opening and come to your own conclusion.

Storytelling in technical writing is not decoration and does not require inventing drama. It requires just three things.
  1. A person, someone with a problem, a constraint and something at stake, usually the writer. A sentence as plain as "this took two days to work out" is among the most generous in technical writing, because it conveys to the reader the difficulty so they don't get discouraged themselves.
  1. Addressing a wrong turn. A tutorial where every command succeeds on the first attempt becomes useless as soon as the reader runs into an issue of their own. Addressing known failed approaches can sometimes be worth more than the one that worked, because a reader is able to gain understanding and a path forward. It also establishes credibility, since anyone can publish a path that worked.
  1. An arc. Something was broken or unclear, so the writer pursued it, and here is where it ended and what it cost. As simple as that is, it works and is a reason readers will continue to the end.

The same principle applies at the paragraph level. Every section should open with a reason to care before it opens with information.

  • "Security groups are stateful firewalls attached at the instance level" - states a fact.
  • "This is the first thing to check when an instance is running and still refuses connections" - states the same fact but making you want to continue reading to know more.

A narrative gives the reader a reason to keep reading, and how you structure it determines whether the reader can follow.

Part 3. Deciding the Shape Before Writing

A simple step many writers skip is the outline, which is why many articles wander. Before you just start writing, you should have a heading template that structures the blog into a logical picture you're about to paint to the reader. Reading only those headings from top to bottom will reveal whether the post is telling the right story.

Weak headings look like this:
Introduction
Background
Setup
Implementation
Conclusion
That is just a filing system rather than the flow of a story. It doesn't give the writer or reader any insight into what they are about to write or read.

Stronger headings look like this:
The $400 bill
Confusion behind CloudFront caching
Setting up the distribution
Tracing a single request
What I would do differently

Each one gives you some information about what you are getting into, and read in sequence that already summarize the blog. Once the shape is settled, you have a high level guide of what each component of that shape has to accomplish for the reader.

Part 4. Stating Your Assumptions Early

Telling someone they need "basic AWS knowledge" is so vague that it's not worth communicating. Be specific. Telling them they "should have deployed at least one Lambda function" gives them something tangible.

The same goes for your tools and versions, because Python 3.11, Node 20 and AWS CLI v2 all behave differently from the versions that came before them and your reader has no way of guessing which ones you used.

Spell out the access you expect them to have as well, whether that is an admin account, a specific set of permissions or a domain they already own.

Two things get left out of almost every prerequisites section:
  • Time and money. Saying that something "takes about 30 minutes and will cost roughly $2 if they leave it running overnight" respects the reader enough to let them decide, and an unexpected bill is the quickest way to lose their trust... permanently.
  • What the post does not cover. This is the quickest way to stop the wrong reader from reading an article they didn't need.

All of that costs a reader about twelve seconds and saves the wrong reader ten minutes. Now, once they know the post is written for them, they need something concrete to follow.

Part 5. Grounding it in Real World Scenarios

An explanation that stays abstract adds friction to the understanding of the reader who has never seen the thing before. Real world scenarios help make your explanation... realistic, inviting the reader to better envision themselves in the story. This can be done in many ways.

Some writers state a scenario early and let it run through the entire piece. For example, the same broken deployment is incorporated in every section and each new concept is introduced by what it does to that one situation. This works especially well for tutorials and deep dives, because the reader ends up building a single mental model instead of several disconnected ones.

Other times you are better off placing a different scenario in each section, which tends to happen when the concepts you're explaining do not naturally belong to the same story. A section on security groups might open with an instance that's running but refusing connections, while a section on NAT gateways can open with a private service that needs to download a package. Each scenario plays its role within that section.

You can also interweave the two approaches, anchoring the post in one main story while dropping smaller examples wherever a point needs support. What matters is less about which approach you choose and more that the reader is kept engaged through a scenario they recognize.

A good scenario is small enough to hold in your head and close enough to reality to feel familiar. Once the reader has a situation they recognize, the next thing they need from you is a path through it.

Part 5. Walking Through It Step by Step

A walk through is where most of the practical value of a technical blog lives, so you'd want to be almost mechanical about how you lay it out. Number the steps, because a reader returning a day later is looking for a specific step and needs to find it quickly.

Keep each step to a single action and include where the reader is meant to be at each point, whether that is a directory, a console page or a particular file, because just saying "add this to the handler" assumes they already have your project open in front of them.

Everything in the post also needs to run exactly as written. A  <your-region> with no explanation of what belongs there, or an abbreviated snippet with a comment standing in for the real code will break the reader's flow.

Additionally, make sure to show expected output after every step. This turns each step into a checkpoint where the reader can confirm they're still on track, so they catch a problem when it happens rather than discovering it at several steps later. You'd want to name the failures you ran into yourself too, something as simple as telling them that "an  AccessDenied response here means their role is missing s3:PutObject " can save your reader an hour of trying to figure it out themselves.

A clear walk through will get the reader to the end, but what makes them trust it is the evidence you put in front of them.

Part 6. Show, Don't Just Tell

The difference between technical writing people trust and technical writing people second guess usually comes down to whether the claims in it can be checked.

Writing that something is "really fast" is vague and makes the read question your claims because they have no way of verifying that. However, if you state and show actually numbers like, "p99 latency dropped from 840ms to 62ms" it gives the reader a number they can later evaluate themselves. It also subconsciously makes them lean more into trusting you because of your transparency.

In practice this means pasting real output rather than describing it, including the parts that can look messy, like stack traces, error strings and durations.
Did you know that someone searching for the exact error message you included is one of the most common ways your blog gets found in the first place?
It also means showing the difference instead of a summary of it, because "I updated the handler to parse the body" is shorter and far less useful than showing the four lines that you actually changed.

This logic also applies in both directions. When you tell the reader something is difficult, show them the difficult part so they can see what they are up against and when you tell them it's simple, show the simplicity of it so they can see how short it really is. Give power to the reader to make decisions.

Some things cannot be proven in a sentence though, which is where visuals come in.

Part 7. Break Up the Text With Visuals

People just don't like reading blocks of text anymore so use visuals to break it up. The right visual helps you communicate at a level text could never do. Ironically, there are no images in this blog :)

Diagrams carry anything with more than two moving parts, so if you catch yourself writing something like, "the request goes from the load balancer to the service, which writes to a queue, which a worker then picks up," you just wrote a diagram you have not drawn yet.

Screenshots cover anything involving an interface, but make sure they are annotated! A bare console screenshot will leave a reader hunting for whatever it is you are describing. Box the field, add an arrow and tell them what to look at.

Fifteen to thirty seconds of video, or a GIF, gives readers a break by changing their consumption method to being more passive and offering you the opportunity to be lot more creative in delivery.

Two rules to abide by here:
  1. Never screenshot code, since it cannot be copied, searched or read properly on a phone
  1. Always write alt text that describes what the image shows rather than what it is

If you only make one visual for a post, make it a diagram of your scenario. That is the image people screenshot and share, which makes it the one that will carry your post to places you can't reach yourself.

Where to Go From Here

Pick the thing you can't stop thinking or talking about. Think about the story you want to tell and sketch out the headings, state what you're assuming, thread in real world scenarios, include any steps, show the output and try you're best to include images.

When you're doing your final read, there's really only one question to ask:
"Is this worth spending my time reading?"
If the answer is yes, publish it!

Authored by:
 Ifeanyi Otuonye  Developer Experience Engineer, AWS
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article