Five common mistakes when writing a technical blog post

A version of this article was originally published on CodeNewbie.org and was authored by Saron Yitbarek.

A little while back, I reviewed over 200 writing samples for a tech writer position. Overall, I was blown away by the quality of the writing I reviewed. The pieces that stood out had personality, understood the newbie-ness of the reader, and had great structure that started with explaining the problem. But what might be more useful for someone looking to improve their technical skills is to look at the common mistakes I saw in the applications that didn't move on to the next round.

1. "It's so simple!"

One of the frustrating things to hear when you're a newbie is how easy code is. You try it yourself and you get stuck, but everyone keeps telling you that it's so simple, which just makes you feel stupid. The intention behind writing "It's so simple!" is to make the topic feel approachable, but it often has the opposite effect. Don't let your readers feel stupid :)

2. Lots of filler language

Try this exercise: the next time you write a blog post, delete the first paragraph. Now read the rest of your post and ask yourself if you feel like anything's missing. Chances are, you won't miss that first paragraph. This is a common editing technique. It works really well because, usually, that first paragraph is filled with fluff: you're trying to give context, provide background info, you might have a few rhetorical questions in there, or maybe you're trying to be funny. For a technical blog post where the reader is looking for solid information, most of that stuff is totally unnecessary and only gets in the way of your awesome blog post. Cut out the filler and get to the point.

3. Too many buzzwords

I've noticed that in explaining a technical concept, many writers end up introducing 4 more technical concepts they don't go into. Sometimes, this is hard to avoid. A tech topic is usually built on top of other tech topics, so you can't eliminate all tech words completely. But usually, the introduction of more buzzwords comes from the desire to be precise and complete, and oftentimes, such precision is unnecessary. The price of being more complete is making the reader feel more confused and intimidated, and that's very expensive. As the writer, it's your job to determine what additional buzzwords the reader should know, and which ones you can fudge for the purpose of focusing on your topic.

4. What's the problem?

Technical tools are created to solve problems. But when we look up definitions and research new topics, the results we get are often so filled with jargon and buzzwords that it's hard to see the "why" behind it all. But that "why" is crucial. That "why" is everything. The more foreign and abstract the technical topic you're writing about, the more important it is to explain to the reader why they need to go through the (often frustrating) process of learning about it. Don't forget to start with "why".

We hope these tips were helpful! And if you have additional thoughts on what makes a great technical blog post, comment below!