I feel for you, in a sense, if you’re reading this post with interest. That’s doubly true if you arrived here by googling something like “how to write technical blog posts.”
I mean, don’t get me wrong. I have no issues with what you’re trying to do—learning to write blog posts. Good for you.
I feel for you because your foray into this topic probably feels like boiling the ocean. You’ve decided to start a technical blog (or maybe a boss is forcing you to), and you’re now in a “where does one even begin with this” kind of posture. Might as well google “how to be a good person” to round out your day.
Well, fear not.
I won’t deign to teach you to be a good person, but I can give you some specific, actionable advice on how to write good technical blog posts. And I’m going to make this guide a lot more tactical and specific than most you’ll find, since “think of good topics” or “get feedback on your posts” are pieces of advice that are somehow both non-actionably vague and completely overwhelming at the same time.
I’m going to give you a specific procedure that will result in you producing an actual post, today, if you’re so inclined.
Your Humble Narrator—I Swear I’m Not a Charlatan
Permit me a brief autobiographical aside here. I don’t particularly relish including this (nor am I just saying that while secretly loving it). Going on about yourself, incidentally, is a good strategy for writing bad blog posts.
But I do want to at least establish a little credibility here, so you can rest assured that I didn’t just publish 3 tutorials to Medium and am now channeling that anemic experience for your benefit. I have a pretty serious background in writing technical blog posts.
These are the traffic stats from DaedTech, a tech blog I started about a decade ago.
I also co-founded the company hosting this particular post, Hit Subscribe, which has produced almost 2,000 technical blog posts for our clients.
So I:
- Have written over 1,000 such posts myself.
- Founded a company that has taught and facilitated others to deliver 2,000 more such posts besides.
That is my life, such as it is. And whatever else I can or can’t hang my hat on, I feel like a credible authority to help you write technical blog posts, at least.
1. Find Actual Questions People Ask
This first piece of advice might run contrary to other things that you read on the topic. I’m not going to tell you to sit around brainstorming, nor am I going to tell you to just write about whatever you’ve been doing lately.
Instead, I’m going to tell you to go find unanswered questions and answer those questions.
This approach has two main benefits:
- You already know, by definition, that there’s an audience for your post.
- Whether you currently care about it or not, this is an excellent way to earn so-called organic traffic (visitors finding you via search engines), which is a nice way to have traffic even when you’re not actively posting in a given week.
How, specifically, do you figure out what questions people are asking? Well, perhaps friends or coworkers are asking about things. Or maybe you’ve had a specific problem in the past, yourself.
Those aren’t bad techniques, but here are a few that I’d suggest instead, since they’re reliable and repeatable.
- Go to a technical site like StackOverflow and peruse the questions folks ask, looking for things in your wheelhouse and, ideally, questions without super-satisfying answers.
- Secondarily, you can poke around more generalized sites, like Quora, looking for the same kinds of questions.
- Use Google’s “people also ask” widget (see image). With this, Google is basically telling you, “hey, this is a question that people ask, and, if you answer it, people will be interested.”
These three sources alone should give you a virtually endless backlog of topics.
2. Establish a Human Reader Persona with an Actual Name
Once you have a backlog of topics and you pick one, in particular, to write about, your next step is to figure out who you’re talking to. And I don’t mean, “software engineers” or something.
Ideally, I want you to think of an actual person that you’re going to write this post for. Barring that, create an imaginary friend.
Who would ask the question, “how do you write a unit test in C#”?
Oh, I bet Sarah on the front-end team would. She’s a Javascript developer who writes unit test, and she’s been talking about wanting to do more server side development.
Great! Understand that you’re now writing a post where your goal is to teach Sarah to write a unit test in C# with a blog post entitled “How Do You Write a Unit Test In C#”. (I’m dropping off the “case” from the question since that’s not actually how Sarah would talk.)
Without a specific person in mind, bloggers—especially newbies—tend to flip into dry, academic-style prose.
Er, excuse me. Let me try again.
Absent a specific persona, blog content has a tendency to be composed with verbiage that constitutes a dry, academic-style.
Yeah, that’s not the best voice for blogging. When someone writes content like that, they’re writing not for the reader’s benefit, but rather considering how they sound. (Perfectly understandable, since decades of primary and secondary education encourage this).
But if you imagine Sarah, and you write to Sarah, you’ll write content that Sarah will like. And keeping her engaged and entertained might not be the easiest with a tutorial style blog post, so you need every advantage you can muster.
3. Define a Concrete Goal for Your Named, Human Reader
Alright, now that you’ve got Sarah as a reader, and an actual question that Sarah would ask, you need to think about her a little more yet.
What’s in it for Sarah?
Every day, millions of things compete for Sarah’s valuable attention, including your prospective blog post. Why should she read it instead of doing all of that other stuff? How will her life be better afterward?
You don’t need to answer this question in any real existential sense, but you should come up with something. In our case, at the end of reading, Sarah will know how to write a unit test in C#. That works, right?
Well, sure, it’s not bad. But I’d refine it even a little more, to make it as tangible as possible.
When Sarah finishes reading your post and following along, she will have her first actual, functioning unit test sitting right there in her IDE. Now that’s a tangible goal. Your mission is to help her get there.
Thinking this way not only ensures that your reader has good reason to pay attention, but it also helps you focus your writing and post structure.
4. Establish Your Post’s Structure with an Outline
Speaking of your post’s structure, let’s do that!
As you get used to writing technical blog posts, you might find that you’re the sort of person who can work without an outline. Good on you, but don’t assume that in the beginning. Start out as someone who outlines the post.
If you’re writing an informational technical post, that’s generally going to mean establishing the goal/thesis of the post and then brainstorming supporting points to be your section headers. If you’re writing a sequence of steps or tips, you might outline things the way I did with my H2s here in this post. Or if it’s pure walk-through, you might not know all of your steps, exactly, ahead of time. But you can still sketch out the gist (i.e. beginning, middle and end or something).
Laying out a coherent structure to things will help you avoid prattling, and will ensure an orderly sequence for the reader. It also lets you audit your own post, when finished, to make sure everything is relevant to the goal/mission of the post.
Oh, and speaking of the overall goal/mission, you should plan to tell Sarah exactly what she can get out of reading the post right in the beginning. This could happen in the first couple of paragraphs, or maybe the first section. But, in either case, plan to convince her very early on that she should continue paying attention because it will benefit her.
Finally, in the conclusion, you should plan to recap what you did and leave Sarah with a takeaway and conceptual next steps. This doesn’t mean you’ll need to rewrite a mini version of your post in a section called “Conclusion.” Just plan to reaffirm her decision to follow your tutorial, and weigh in a little on what she might do next with her newly written unit test.
This makes a current reader more likely to come back as a repeat, future reader.
5. Write the Post As If You’re Writing a Detailed Message to Your Reader
Once you’ve got a gameplan in the form of your outline, it’s time for the most important part of writing a blog post: writing the blog post.
Don’t overthink this part. You don’t need to adopt some kind of persona or alternate speech patterns. Just imagine you’re writing a detailed email to your colleague, Sarah.
You want to provide thorough instructions, of course. And you want to use clear and direct language. But you also just want to imagine that you’re having a text-based conversation with your reader.
As she’s trying to figure out how to write her first unit test, Sarah already has enough cognitive weight to contend with. She’s busy learning stuff. She doesn’t need you to construct weirdly formal sentences or throw her written curve balls of some kind on top of it.
So keep it clear, concise, and conversational. Throw in a joke or two for her benefit, if you’d like and that’s a normal mannerism for you. Do you. But make sure to stay focused on your mission for Sarah.
6. “Debug” the Post As If You Were Your Reader
With your post now written and staring back at you from the CMS, you’re not quite done. You might think it’s time to edit your post, but nah, not so much.
I mean, if you catch mistakes you made, then great. But if you’re writing a technical post, you’re probably not a copy editor. And you’re either going to have one of those or not, depending on your situation, so que sera sera.
The debugging I’m referring to here isn’t a matter of linguistics, but fitness for purpose. If you’re teaching Sarah to write a unit test, you need to make sure that following your instructions to the letter will actually result in a working unit test.
This isn’t the easiest thing to do, but do your best. Follow your own instructions as if you were a machine, doing only exactly as you’re told. Ask yourself questions like these:
- Did you miss some steps?
- Have you forgotten about some prerequisites for Sarah to succeed?
- Is anything unclear or vague?
You’re basically doing a dress rehearsal to anticipate what issues you’ll have.
(This step obviously applies a lot less faithfully to a purely informational style of post.)
7. Just Ship It and Stop Fretting
This last step is arguably the most important one, I feel. And I don’t mean that in the sense that not publishing the post makes the whole endeavor kind of pointless.
Rather, I mean that the “just” in “just ship it” is the most important thing for bloggers, newbies in particular. Write the best post you can, give it a pass to make sure the reader can follow, and then just send it out into the wild to sink or swim.
Danielle Morrill, who built Twilio’s impressive following and community, had this to say in a talk she gave.
It’s never going to be perfect, just like your product. If you wait so long that you’re not embarrassed of anything, you’ve waited way too long.
I love the comparison of prose to the wisdom of building and shipping a SaaS as a startup (“if you’re not embarrassed by your first version, you waited too long to ship.”) It is the exact same concept. No matter what you say in a post, no matter how perfectly you write it and refine it, if it gets sufficiently popular, someone, somewhere is going to tell you you’re wrong, disagree with you, and if it trends on Reddit, probably tell you that you’re a terrible person or something.
Of course, if you’re a relatively new blogger, perhaps file that under “good problem to have,” since it means you have a ton of readers. The more likely early outcome, frankly, is that you have few readers and none of them actually really care what’s in your posts, initially.
Whatever the case may be, err on the side of shipping. Do your diligence, and then turn your post on the world. Because without that step, the rest of this is academic.
