cft

How to Write Clear Tech Articles (That People Actually Read)

I'm going to talk about some of my own observations, and the many ways I’ve discovered that one can fail.


user

Andrew Long

3 years ago | 4 min read

I feel like I’ve been writing just long enough to have figured out what works for me, and what really, really doesn’t. I write primarily technical articles dealing with programming and security — you know, really exciting stuff.

Writing tech articles is such a weird balancing act that can so easily fall flat, making you sound either dull or uneducated on the subject. I'm going to talk about some of my own observations, and the many ways I’ve discovered that one can fail.

Research all the things

I rarely go into an article without either real-world experience or hours of research. Often, it’s both. I don’t care if I’ve worked with this technology for 2, 5, or 10 years — I’m going to research everything before I start writing, and keep it up while I’m writing.

Maybe it’s my own insecurity, but I’m just not comfortable stating anything as the gospel truth without checking the facts first.

I don’t usually do it this way
I don’t usually do it this way

This hasn’t always been the case. In my early days of writing, I would sit and type out an entire article about so-and-so subject completely from memory and life experience. While there’s something to be said for sharing experience, it’s not always correct or best practice. I learned the hard way that people on the internet really, really love letting you know when you’re wrong.

While feedback is great and all, it really took the wind out of my sails. The takeaway here is simple: don’t beat yourself up over being wrong, just improve your writing process and move on.

Oh, and do your research.

Break up the monotony

This can be applied to nearly any article you write, regardless of subject matter. Attention spans are pretty short across the board, and the best way to lose a reader is to throw a wall of unformatted text at them. It’s just offensive. When I open an article and see no visual breaks or section headers, it instantly feels more like a chore than something I can enjoy reading.

Don’t do that to your readers. It’s just mean. Break everything into easily digested chunks. People also expect to see things organized into sections, with titles and pictures (especially on Medium).

While you’re at it, make some of the important points bold. Emphasize things with italics. It makes things interesting and expressive, like you’re getting a little piece of the author’s personality with your information. Bringing me to my next point…

Simplify where you can

You might think that you sound more intelligent when you explain complex concepts in high level terms. To some you might, but it’s not a great habit to have. I’m not going to tell you to dumb everything down, but you need to understand that not everyone is coming into the article with expert knowledge. You will probably have a lot of readers checking out your content to learn something.

ah yes, I know some of these words
ah yes, I know some of these words

Do you know a great way to dissuade someone from listening to you? Speak above their head and offer no explanation.

One thing you can do to avoid this is offer up some footnotes, figures, or parentheticals to round out concepts that may not be common knowledge. I’m not saying that you have to go full on ‘explain it like I’m five’, but don’t assume everyone has the same knowledge as you.

You’ll actually seem smarter if you break things down, it shows that you understand the content.

Crack a joke here and there

I get that not everyone is a comedian, but you do talk to other people, right? You know what makes them chuckle? Put that in your work. Bringing a little quip or sass into a technical article is kind of a breath of fresh air (you’re paying attention to my italicized text now, aren’t you?).

Point out flaws in your own understanding in order to illustrate what the correct info is, joke about funny terminology, just whatever comes to mind.

Searching for “funny” stock images never actually turns up anything funny
Searching for “funny” stock images never actually turns up anything funny

Eventually, you’ll find your voice. It’s a fake it until you make it kind of venture, so don’t be afraid to try on a lot of hats. You might find that outright cracking jokes isn’t your thing, and maybe you prefer to just be insightful or witty — that’s ok, too. The point is to offer up a little humanity with the sometimes laborious subject matter.

For the love of Christmas, cite things

Nothing makes me feel like someone is a little full of shit more than having dozens of ‘facts’ and figures with no citation. Are you expecting me to Google these things myself, like a caveman? No, I won’t just trust you on this. If you tell me that 38% of all computers contain extraterrestrial malware (note to self: screenplay idea), you need to show me the whitepaper or other legitimate source.

I don’t accept sources with man-buns
I don’t accept sources with man-buns

Not citing credible sources, or any sources at all, when you’re dealing with things that are concrete (like figures) makes you seem like a snake-oil peddler. It’s a cheap sales trick to throw a bunch of unfounded numbers at someone to sway their opinion, and it’s a really great way to lose credibility.

Wrapping it up

Oh, wow, this is awkward. I’m both telling you that you need to always find a great way to wrap up your articles, and trying to wrap up this article. I find that the easiest way to do this is just summarize the main points of the article and end on a good thought.

As long as you’re doing your research, paying attention to flow and formatting, and citing when you need to, you should have no problem pumping out great articles. Write about what you love and what you know, then rest is just refining a process.

Upvote


user
Created by

Andrew Long

Ethical hacker and IoT security specialist.


people
Post

Upvote

Downvote

Comment

Bookmark

Share


Related Articles