here are my top tips on technical writing after 8 years and 700 posts

Since Dec 26th 2009, I have writ­ten reg­u­lar­ly on this blog on a vari­ety of tech­ni­cal top­ics. Suf­fice to say that I have had a lot of prac­tice of tech­ni­cal writ­ing!

I love learn­ing, and I love shar­ing. What I learn I like to share through writ­ing, as it also helps me solid­i­fy my under­stand­ing too.

Over the last 3 months, my posts have received around 75K views per month across medi­um and this blog. So the evi­dence sug­gests that my writ­ings aren’t turn­ing read­ers away at least!

So to help more peo­ple share their knowl­edge and insights, here are a few sim­ple rules that I fol­low when I write.

Mind the “curse of expertise”

The most impor­tant rule of thumb is to always remem­ber you are the expert of your domain. When you share knowl­edge & expe­ri­ence, you need to be mind­ful what assump­tions you’re mak­ing of the read­er.

Espe­cial­ly when you dis­cuss the mer­its or prob­lems of an approach. Always state your assump­tion and con­text explic­it­ly up front. This helps the read­er under­stand WHY you’re doing this, and the con­straints you’re work­ing with.

In the immor­tal words of Simon Sinek, start with why, which brings us to the next point.

Sell the problem, NOT the solution

“Brad, sell me this pen”
Like that great scene in “the wolf of wall street” where Di Caprio asked Jon Bern­thal to sell him a pen.

Cre­ate the demand, then sup­ply the solu­tion.

Sell the prob­lem to the read­er. Help them under­stand why it’s a prob­lem worth solv­ing. The mer­its of your solu­tion are irrel­e­vant with­out an inter­est­ing and worth­while prob­lem.

Where pos­si­ble I try to set out what a “good” solu­tion would look like, and what prop­er­ties it should have. After describ­ing the solu­tion I would then fin­ish off with the trade­offs I have to make. This would usu­al­ly evolve around the pil­lars of cost, com­plex­i­ty and effi­cien­cy.

If you don’t define what “good” is up front, then it’s easy for cog­ni­tive bias­es to creep in. We often sub­con­scious­ly bend the def­i­n­i­tion of “good” to fit our solu­tion, and lose objec­tiv­i­ty in the process. We all have this con­fir­ma­tion bias, there’s no escap­ing it. But defin­ing “good” ahead of time helps keep us hon­est with our­selves.

Keep in mind that your solu­tion might only work in spe­cif­ic con­texts. If peo­ple adopt your solu­tion with­out under­stand­ing the con­text in which it worked, then they risk fail­ure. Worse yet, if the fail­ures are not obvi­ous enough, then you might have start­ed anoth­er car­go cult

Keep it short

On medi­um, you can see how long your post takes to read and how many peo­ple read it start to end. Unsur­pris­ing­ly there is a clear trend that longer posts have a low­er read %.

I com­piled the stats for my posts relat­ed to server­less and this is what I see.

This is reflect­ed in my per­son­al read­ing habits too. I tend to fin­ish longer posts over sev­er­al sit­ting as I often lose my atten­tion span mid­way. I’m sel­dom able to fin­ish a long post in one sit­ting, even if I ‘m real­ly engaged by it.

What that means to you is that you should keep things short, punchy, and to the point. Don’t linger with your words and try to explain things to the Nth degree.

If need be, use bul­let points, and keep each to one line.

Write the post, then read it back a few times. With each run, cut out unnec­es­sary words or rephrase sen­tences to make them more con­cise.

For exam­ple, “to be or not to be, that is the ques­tion” might be vague and leaves a lot to the read­er. The longer, more expan­sive ver­sion is actu­al­ly far less clear!

Cour­tesy of Kevlin Henney’s talk “7 inef­fec­tive cod­ing habits of many pro­gram­mer” —

Be honest

Goes with­out say­ing :-P

Picture says a thousand words

Apply com­mon sense, too many pic­tures is also not good.

Also, keep pic­tures rel­e­vant. We all love cat pic­tures, but too much of it (or used out-of-con­text) is off putting.

Start strong

I fol­low this advice when giv­ing talks as well, and try to kick off a pre­sen­ta­tion or post with a strong mes­sage.

Think of your reader’s atten­tion span as a cur­ren­cy. You have to earn the audience’s atten­tion before you can spend them on tech­ni­cal dis­cus­sions.


So that’s it, 6 sim­ple rules that I fol­low when­ev­er I write. The freecode­camp folks also have some very good advice for writ­ing on medi­um.

I hope this post helps you improve your writ­ing. If you have any sug­ges­tions on how I can improve my own writ­ing style, please feel free to let me know via the com­ments below.

Hap­py East­er every­one!