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.
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.
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.
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.
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.
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.
Ethical hacker and IoT security specialist.