In-Depth

3 Ways To Write Better How-To Technical Articles

Good IT advice isn't worth much if it doesn't land with your audience. Here are Adam's top three tips for writing technical articles that won't leave readers scratching their heads.

• By Adam Bertram
• 09/24/2019

Do you have a tech blog and enjoy sharing your experiences in learning? Maybe you're an IT pro who loves sharing the latest trick you picked up at work.

Sharing your skills with a tech community via the written word is a rewarding experience. It feels great to get e-mails from readers telling me how one of my columns helped them solve a difficult problem.

Writing is rewarding, but if you're not getting through to your audience, you're wasting your and your readers' time. There's nothing worse than noticing a column title that hints at solving my problem only to find that it's incomprehensible. I've found myself shouting at my laptop in frustration when an article just isn't getting through.

"What OS are you doing this on? This doesn't look at all like what I see."

"What do you mean, 'Click here'? Where is 'here'?"

"A simple screenshot would have saved the last hundred words you just wasted my time with."

But it doesn't have to be this way. Instead of forcing them to angrily click away from your article, you can leave a reader feeling like they've accomplished something. If you do it right, you can even leave a reader happy with a solved problem -- and also feeling entertained! But you first must learn how to write informative and engaging content. Quell your readers' frustration by following these three tips.

Tip #1: Solve the Problem
I've alluded to this multiple times already, but it's worth restating: Above all else, solve the reader's problem. Why did the reader come to your article in the first place? Was it because they wanted to learn how to create an Azure virtual machine? Are they stuck on a step in the documentation for setting up a SQL database cluster? Are they looking for a way to process items faster with PowerShell? Help them do that!

Recognize that every how-to article has an associated "problem." That's the nature of a how-to article. Readers want to either learn a new skill or fix an immediate problem they've run into. Every reader has a problem you can solve with your writing.

Don't go down rabbit holes and veer the article out of the problem's scope. Even if you are interested in one particular area, don't indulge yourself because you want to write about that piece more. Think of the reader. What did they come to your article for? Stay on track and solve their problem in the most concise, engaging way.

Tip #2: It's All About the Reader
When you write on a personal blog for your own documentation purposes, go nuts. Write about whatever you want and make it all about you. You have that right.

But even if you provide reliable content that your reader benefits from, it's not making the same impact unless you make it about them. Why? Because they're reading your article from your point of view. They're reading your experiences. Make them feel that same sense of accomplishment you have.

Don't ever use personal pronouns like "I," "me," "my" or even "us." Use "you" and "your," instead. This subtle shift of word choice is powerful. It gives the reader a sense that they are the ones learning how to solve this problem. It gives them a sense of accomplishment when you walk them through a process. They internally feel like they were the ones who figured out the problem on their own.

Congratulate them at the end for learning a new skill or fixing the problem. Stoke the reader's ego a bit if you feel the need. When you start a new article, remember this is not about your experience; it's about theirs.

Tip #3: Keep It Conversational
Many tech writers write Web articles the same way they do documentation. Documentation is dry, uninspiring, black/white, straight to the point and boring to read. Although it's important to inform in an article, you don't have to make it feel like reading an IETF RFC with technical jargon and dry details. Liven it up!

Treat every article not as an encyclopedia entry but more like a conversation. Introduce topics before you talk about them. Give summaries of what the reader has learned through the article. Make ubiquitous use of transitions like, "Now that you've learned how to do X..." or "Let's now dive into figuring out that pesky registry issue."

Don't use technical jargon when you don't have to. Instead, write how you talk. Explain concepts in an easy-to-understand manner and forget sounding "professional."

Summary
Writing technical articles can be a rewarding experience. It's great to feel like you've helped someone get past a sticking point or just entertained them enough to have a better day. Treat technical articles not as technical documentation but as short stories with the tech details sprinkled in.

Want to learn more about writing better technical articles? Be sure to check out my e-book, "Teach Me: How to Write Better Technical Articles that Make Money."