Blog Writing for Developers

Writing is one of the most powerful forms of communication, and it’s useful in a multitude of roles and contexts. As a blog-writing, documentation-authoring, twitter-shitposting DevEx engineer I spend a lot of my time writing. Recently, someone paid me a very nice compliment about a blog I’d written and asked how they could learn to write like me and what resources I’d recommend.

Never one to miss a chance to write and share something, here’s my response to this 🙂

To begin with I want to cover briefly the motivations behind writing.

Why Do I Write? 🔗

Firstly, I like to share information. That could be a new tool or technique that I’ve learnt, a clever trick I’ve discovered, or sometimes away from the technical and into the realms of life pondering and navel gazing. In the case of this very blog, it’s to share my thoughts on something that interests me. I could have written some notes and sent them directly back to the person who asked the original question, but if it was useful to them it’s hopefully useful to others—so therefore it’s worth writing up and publishing.

The second reason that I’ll write is to learn about something. It’s one thing to hand-wave one’s way through a presentation. It’s another to commit pen to paper (well, bytes to disk) and explain something. Quite often I’ll realise that there’s a gap—or gaps—in my knowledge that I need to explore first before I can properly write about something, and that’s the very reason that I do it.

There are several pleasant side-effects from writing too. Anything in the public domain (such as your blog, but also open-source project documentation, etc) helps establish your credibility in an area and awareness by others of you. We may never reach the stratospheric heights of someone such as Kelsey Hightower, who has wowed a generation of developers with their Tetris-playing skills, but being known as that guy who wrote a really useful blog that helped others is still a really nice feeling 🙂

HOW do I Write for Developers? 🔗

🛑 STOP! Watch This First 🎥 🔗

Go and watch this excellent lecture called The Craft of Writing Effectively. It’s given by Larry McEnerney who is the Director of the University of Chicago’s Writing Program and knows a thing or two about writing. There are direct parallels between his observations on how and why academics communicate, and communication between developers.

👉🏻 I’ve seen it recommended several times but to my embarrassment, the length put me off—but I wish it hadn’t as it’s superb.

If you’d rather listen instead of watch you can use yt-dlp to download it as audio (--extract-audio --audio-format mp3).

So, how do I write for developers? 🔗

Each writer will have their own approach to writing, and it will vary based on the audience and purpose too. A report for publication in an academic journey will have a different structure to a shitpost on Twitter. A blog aimed at developers will read very differently from the documentation from the depths of a product manual. Each medium and audience is valid; the knack is making sure that your writing lines up with it.

When I write I try to write for myself—a developer, interested in a thing. That could be a new technology, an in-depth explanation, a random musing on life, or anything else. Would I like to read the thing I’ve read? Does it avoid the pitfalls that plague the soulless bland crap that some companies churn out, stick an emoji on, and call developer marketing?

There are three key dimensions that it’s useful to consider here:

clarity
personality (also called voice)
uniformity of content.

You can roughly overlay these dimensions across the range of written materials that we might write:

Things aren’t always so simple, and for some platforms in particular there’s quite a range:

What do these different dimensions mean in practice? Let’s explore that.

Clarity is Key 🔗

The first of these dimensions is pretty straightforward and shouldn’t really vary. Whatever you write, for whomever you write it, it has to be clear. Writing clearly means everything from sentence construction and paragraph breaks through to the structure of your article. It can be surprisingly hard to do but is crucial if you want to write material that people will want to read.

One neat trick when it comes to clarity is to remember that what you leave out is as important as what you leave in. This is going to be very context-specific. Documentation, by definition, should be comprehensive. A blog, on the other hand, might want to get to the point sooner and just provide a link to background material for the reader should they want it. Less is often more, as they say.

Some types of writing are going to have greater scope for individuality than others, but all have the potential to at least be accessible and clear. For example, just because you’re writing documentation doesn’t give you a pass to copy and paste the requirements doc in all its generic and obscure complexity. Write documentation that you as a developer would like to read. It can be complex and precise, yet still accessible.

Personality and Voice 🔗

Should the ‘voice’ of the author be allowed to come through in the writing?

This is very much a sliding scale. I’ve jotted down some of the characteristics you might associate with either extreme of the scale. This is not to say that by definition you’d put cuss words into a blog so as to convey your voice—but as an example of something that you might see at that end of the spectrum and definitely not at the other.

How you decide where to pitch your voice on this scale will come down to your preference, audience, and general area and discipline. If you spend much time on Twitter you’ll notice that InfoSec Twitter is different from DevOps Twitter, which is different again from DataEng Twitter. Each has its own cliques and customs, and also a varying range to which an author’s voice shines through in published writing.

You’ll generally find that generally writing mediums such as a project report to stakeholders or product documentation requires a neutral voice. That’s not to say boring, but it is to say that a certain uniformity is required. In the case of a project report, the message mustn’t be obscured by colloquialisms and the such. And can you imagine the cognitive dissonance if a set of documentation were written by multiple writers each looking to stamp their personality on the pages?

When we get to things like blogs and other types of writing we deliberately want to include some personality. How much is up to you to calibrate with your audience and yourself. There is a “Goldilocks” zone here—enough personality and genuine voice coming through to convince the reader that they are reading something that was written by someone who is actually interested and informed on the matter, but not so much that it gets in the way of the content.

Uniformity and Standardisation 🔗

This has a strong relationship with personality and voice but relates a lot more to the structure and content of the material

Using the example of blogs, you’ll find that blogs for a company or project are going to have a strong focus on the consistency of messaging and structure. There’ll be an introduction, there’ll be context; it’ll be comprehensive.

Compare that to a personal blog that may sometimes be not much more than the gutterings of a developer wanting to log an error message and solution for future Googlers. They might flesh it out into a longer article, but that’s not necessary for it still to have value.

A Holistic View 🔗

It may seem like there’s going to be a linear relationship between the two dimensions. As we decrease the amount of personality coming through in an author’s writings, we’re also going to move towards a much more standardised set of writing.

I’d suggest that it’s not always the case.

A startup may value personality much more over standardisation, perhaps only really dropping the voice when it comes to something like documentation (and even then, perhaps not entirely).

At the other end of the scale, some companies—usually large corporations—have the habit of squeezing the last inch of life out of any kind of writing, making the relationship a much different one.

Here there’s little voice even where you might hope to find it, and that rapidly drops off into nothing very soon after:

The wildcard within this is the social media teams of large companies who are given the remit to be Funny and Engaging, but this is usually outside the scope of developer writing and more into the field of condiments and fast food chains

Structuring your Blog Writing 🔗

Like a favourite pair of jeans that’s well-worn, comfy, and slightly saggy round the arse, I have a go-to structure for writing. Come to think of it, I use it for lots of conference talks too. It looks like this:

Tell them what you’re going to tell them
Tell them
Tell them what you told them

What this looks like in practice is something along these lines:

An intro

What is this thing, and why should the reader ~~give af~~ be interested?

This could be a brief explanation of why I am interested in it, or why you would want to read my take on it. The key thing is you’re relating to your audience here. Not everyone wants to read everything you write, and that’s ok.

Let people self-select out (or in, hopefully) at this stage, but make it nice and easy. For example, if you’re writing about data engineering, make it clear to the appdev crowd that they should move on as there’s nothing to see here (or stick around and learn something new, but as a visitor, not the target audience).
The article itself
A recap

Make sure you don’t just finish your article with a figurative mic drop—tie up it nicely with a bow (a 🙇🏻 or a 🎀, either works).

This is where marketing would like to introduce you to the acronym CTA (Call To Action) 😉. As an author you can decide how or if to weave that into your narrative.

Either way, you’re going to summarise what you just did and give people something to do with it next. Are there code samples they can go and run or inspect? A new service to sign up for? A video to watch? Or just a general life reflection upon which to ponder.

✍🏻 The Physical Act of Writing: JFDI 😉 🔗

At the risk of repeating the owl meme I would give the following advice: just start writing!

I don’t mean just go write an article. I mean start writing something, anything.

Some notes, some snippets, some whole paragraphs. It might even look like this

The point is you now have something. The sections and threads of a story start to fall out as you write more. What starts as one section perhaps becomes two as you realise there are individual elements to tease out.

Iterate, iterate, and then iterate some more.

That random link you made a note of, where does it fit in what you want to say? Is it pushing the need for a new section or tangent, or is it actually not so relevant and you can park it? Not sure? Well just leave it there and think about it again on the next pass round.

I’ve recently found that using a Pomodoro timer is an effective way of getting me to focus, and to take a break. Instead of staring at a screen, descending into a pit of despair at the stagnation of an article, you spend a chunk of time and then step away. Perhaps you come back to it after the break or maybe wait longer. Like many problems in life, things resolve themselves given time to marinade in the recesses of one’s brain. That paragraph that just wouldn’t write itself will come spilling out of your eager fingers onto the keyboard. The section you thought you’d nailed—turns out you didn’t and it needs a rewrite. But all these things come with time and iteration through the text.

Find a really good reviewer and copyeditor 🔗

You might think you’re good at writing. You’re probably not that good at writing that the eye of an excellent copyeditor won’t improve it, nor the tactful input of a good reviewer enhance it.

Good copyeditors will respect the voice that’s present in your writing and work to preserve it whilst improving the clarity and grammatical accuracy of what you’ve written.

Good reviewers will grok what you’re saying and help distil and mould it into a better shape.

Ah, the meta-blog post about tooling. Each to their own, but here’s my stack:

Resources 🔗

We’ve covered the why and the how – but what about the what?

What to write will often come from the “Why” above, but let’s imagine that the creative juices aren’t flowing and you still really want to get a blog written.

A really excellent place for ideas is the community around the thing you want to write about. Go and lurk (or even better, join in) at StackOverflow, Twitter, Slack, Discord…wherever the community is:

What questions do people repeatedly ask?
What are the anti-patterns and misunderstandings that you see?
What are the new trends?
What cool things can you do with $THING

In short, if it would be interesting to me then I would write about it.

Make sure to also watch this lecture in which the concept of value and ideas is discussed. tl;dr if you aren’t writing about something interesting to the reader, it has no value, regardless of its value to you.

What Not to Write? 🔗

This is a very personal preference. I’m not keen at all on growth-driven blogging styles. You know the sort: listicles, SEO bait, etc. It’s low-grade, developers see through it, and it tarnishes the blogger’s image IMHO. That said, if you write a good blog, there’s no reason not to structure it such (“Top Five Tips for Successful Developer Writing”) but put the horse before the cart, not the other way around.

To summarise this whole article, bear in mind that these two statements are not mutually exclusive:

Write for yourself. Work out what you would like to read, and write it.
Think of the reader and what value you’re providing to them in your writing.

That’s because as a developer writing for developers, you are the reader.

Oh, and did you watch Larry McEnerney’s lecture yet? 😊