So. You have trouble writing blog posts?

Build on this structure and stay friendly to make your ideas shine!

See what I did there? (CC-ZERO Image by Comfreak on Pixabay)

Bleurgh! Writing can be tough. You’ve worked on something for ages, the process meandered all over the place, and now you need to write it up in a way that’s clear for other people. What a pain.

Well guess what!? You can read this post (this very one, you’re already doing it! Go you!) then steal some sections to have a handy list of things to build your post around.

Right, let’s:

When you get stuck, come back to this ⬇

The perfect post blends the answers to two simple questions:

By answering the first question we keep it fun. By answering the second, we avoid adding distractions and mess.

Start at the end!

You probably got a pretty cool idea? Something fun like a Mood Mirror? A cool tech thing like a 3D archive? A buzzword to unpack?

Make sure that idea is right at the top of the post. Up there in the title! People love posts that solve problems. Put the problem in the title. Put your solution in the subtitle.

At school and university we’re taught to start essays with our research question and work through to our answers or conclusion. Turn that upside down. You’ve got to hook people with the headline. Once you have them on board, you can lead them through your journey: Marco Polo leaving Venice is not a headline, getting to China is.

Keep your reader on the path with signposts

How not to do signposts? Even these are better than navigating without any! (CC-ZERO by kbhall17 on Pixabay)

You had a great hook in your title and first paragraph, but if it all unravels, people will get lost — then leave. If your post is technical and/or lengthy people need to be able to leave and jump back in.

Good headings, signposts around your words, are the key tool for this. What about listing your headings in the opening section? This works like a contents section or a title slide: it helps people get a handle on what to expect and can help people browsing through.

For me, headings are also the best place to start the writing process. Just blurt out your key points as bullet points or fragments. Don’t worry about making sense at first.

Once you have three or four key points you can start fleshing them out. You might find that you need to swap them round or that some can be deleted. Others might get bigger and have to be split up. Often, it’s easiest to leave the title until the end!

Who’s going to get your message?

Imagine someone. Write for them.

Sometimes imagining your reader is easy:

Your post explains the solution to a problem?
Your reader is the person with that problem.

You’re writing about cutting-edge tech development?
Your reader is an early adopter that you can tempt with a futuristic vision.

You’re ranting (sorry, writing a passionate diatribe) about something?
You might hope to convince your opposition: aim for a sympathiser.

Spend a few minutes browsing around some posts on similar topics and think about why some of them are easy to read and others are like wading through cement. It’s likely that the boring ones miss lots of the elements I’m suggesting, but they might cover quite a lot of them and still seem terrible because they’re not aimed at you.

That’s fine: you need to admit that you can’t please everyone either. If your message lands for the reader you imagine, they will help boost and spread it further. You have to go through a little process: imagine the person who should care about your idea, and then package your idea so that person will want to read your blog post straight away and get value from it.

Are you David Attenborough or Emily Graslie?

The voice you use has to match your message and your reader.

We all love David Attenborough telling us marvellous things about wildlife.

Blue Planet YouTube clip: BBC

He’s the boss. You believe everything he says. You feel wonder. There’s dramatic music. He makes fish into heroes. You soak it all in.

On the other hand, there are other ways of presenting the ‘wonders’ of nature:

! ! ! ! G R O S S ! ! ! ! W A R N I N G ! ! ! !

Squirrel McNastyFace: BrainScoop YouTube video

Emily Graslie’s incredible Brain Scoop YouTube channel goes behind the scenes at the Chicago Field Museum. That early video is pretty rough-and-ready (they get more polished) but the enthusiasm of the hosts, jokes, gross-out moments and science facts all blend together pretty well. I’d definitely struggle to have more fun with a tumorous grey squirrel.

Choosing the right language is also important. Anna, the zoologist, mentions squirrels being ‘arboreal’ and David Attenborough talks about calculating ‘altitude and trajectory’. These aren’t words that everybody comes across regularly, but they’ve decided that the viewer can pick them up from context. Were they right?

If you’re writing for a technical audience then it’s probably okay to casually mention APIs, version control and your favourite JavaScript libraries. This may sound obvious, but it’s incredibly easy to slip up. If in doubt, bounce it off someone friendly, check it makes sense.

Hug your critics: tackle the ‘What about X?’

Embrace your critics! FREE HUGS (CC-ZERO by tozik on Pixabay)

Phew! This all sounds pretty ambitious — it’s hard enough to get your head around your idea, let alone write it up with all this extra stuff in the mix. It can be paralysing. This very post got stuck as a series of bullet points for weeks! You’ve probably got some thoughts about why these suggestions won’t work for your blog post? Well, I’m going to try and answer them.

And guess what!? I suggest you do the same — try and think of the ‘What if?’ and ‘Yeah, but…’ reactions you might get and tackle some of the biggies before you wrap up.


Oof. This one’s a killer. It made me drop out of University. Seriously.

The best solution for me though? Write for that one imaginary person we discussed above. If you have a tech background, this is basically the same as defining a user and only worrying about pleasing them. Don’t worry about the edge cases. I also think about it in terms of audiences. Your post doesn’t have to be the definitive greatest piece of writing about X ever written. It just has to be be fun enough and clear enough for that one group who need it now.

Types of posts | Types of publications

These fundamentals are really good to build from to make sure you keep your reader engaged. But, what if you’re writing about something really specialist? What if your post is going to be on a site with very different material? Well, firstly, make sure you signpost this to your reader so they know what to expect.

For example, a technical deep dive can be a challenge to keep fun. Don’t be afraid of the terminology and complex ideas: you have to use them. But, you need a really clear structure and should give your reader the tools to follow up on any confusion (Wikipedia links are your friend!). But remember, you’re still writing a blog post: not the technical manual or documentation!

Writing up an event is another type that can be tricky. You’re not a Condé Nast travel writer — do you really need to describe the weather, the building and the coffee? Perhaps you do. If you’re writing for a close community of people you can be sure that the group who missed out will love it. But more often, it’s much better to concentrate on the lessons from the event that will be useful for the broader community. You don’t have to tell it in order. What three things stuck in your head?

Keeping complicated concepts clear

JavaScript, javascript, js, JS ?
Till, untill, until ?
Aluminium, Aluminum ?
Muhammed, Mohammed, Mahmet ?
Beigal, Bagel, Beigel ?

There’s no hard and fast rule for this. Language is delightfully, agonisingly tricky sometimes. But, if you pause to think about a word, odds are that your reader might get confused by it too. Re-read the sentence, the paragraph, the section! Make sure it makes sense and for everyone’s sanity make sure you choose one spelling and stick to it!

The Guardian maintain a really useful style guide. It includes gems such as:

  • moon walk
    what Neil Armstrong did; moonwalk what Michael Jackson did

Find points of connection

That imaginary reader you’ve worked so hard to conjure? Empathise with their struggles.

You’re struggling to write about your key idea? Acknowledge that it’s because it’s a complicated idea. Writing is tough. Explaining, emoting, engaging, empathising. Sometimes you even have to do things that don’t start with the letter E.

Wrap it in a ribbon

Finish up by giving your reader some really useful nuggets to take with them.

Hey, you’ll have noticed that I used a few free-to-use images? They break up the text and help illustrate ideas (in my case pretty flippantly!). Here’s my first nugget: free-to-use images are easy to find on sites such as Pixabay, Unsplash, Pexels and Wikimedia Commons. No infringement worries, just credit and link!

What’s next? They’ve read your blog post. You’ve caught their interest. Give them somewhere to follow up. How do they find you to pass on questions or critique? Where can they find out more about the topic? What if they want to build what you built? Go where you went?

Well, finding out more about writing blog posts is easy. The amount of content on good writing is overwhelming. The bad news is that lots of it isn’t even as useful or fun as what I’ve scribbled here.

However, here’s some gems I’ve found useful recently particularly for writing blog posts:

Finally, you want to restate your key points. We’ve covered the fundamental questions to ask about your reader and your ideas. We’ve looked at structure and signposting, voice, anticipating critics and wrapping stuff up. Did it make sense? Can you see how to apply them to your work?

This post was originally written as an internal top tips document for the team at Cogapp (that’s why it’s aimed at tech writers).
Thanks to Gavin Mallory and Andy Cummins for the time to write it while I was there and the permission to publish it now!

Cultural comms and digital bod. (On a partial mental health break) Poorly preserved archaeologist remains. Formerly @cogapp @YorkMuseumTrust

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store