Writing technical blog posts have always been something I've struggled with. I never know how much background to add or what concepts I need to explain. At times, I'll even question the point of the article - "what value do I bring?". I hope I'm not the only one who thinks that writing a technical blog post is hard.

Last year (so pumped I can say that now), I focused on improving this skill. I attended a technical writing workshop at Ruby Conf US run by Noel Rappin. Sidenote: he runs a newsletter, definitely worth taking a look at! I also read countless blog posts, and Stephanie Morillo's book: a Developer's Guide to Content Creation.

I want to share with you everything that I've learned from that experience. And also what has personally worked for me. I'll lump my learnings into two categories - understanding your audience, and the process of writing the post.

Understanding your audience

First things first, you need to know who you're writing for.

I've seen a lot of advice that says to "write for yourself". While the sentiment is there, "yourself" is a very vague audience.

Being specific with your audience helps guide how you write your post.

Understanding the audience comes in two forms:

• What is the problem they're having?
• What is their skill level (beginner, intermediate, expert)?

What is the problem?

An "aha" moment I had was learning that a problem is not the same as the solution. Let's dig into what I mean. Here are some examples of problem statements.

• Problem 1: I want to use 11ty* to build a site.
• Problem 2: I want to build a fast, simple blog that uses markdown to write posts.

*11ty is a static site generator

And here are some solutions to the problems:

• Solution 1: Here's how to use 11ty
• Solution 2: Here's how to use 11ty

Notice how the solution to these problems is the same. But writing for problem 1 would be harder than problem 2. In general, avoid framing a problem with the same words as your solution. Having a very specific, well-scoped problem helps guide your post.

Writing for a skill level

Part of understanding the audience is also understanding their skill level. Noel Rappin suggests putting them into three categories; beginner, intermediate, and expert.

It's easier to write for beginners and experts. But harder to write for intermediate. Writing for intermediate is hard because you don't know how much information to include or omit.

If in doubt, err on including more information. Structure your post so it's easy to skim (more on that below!). Experts are great at skimming through a blog post to find information that is useful for them.

Most importantly, be empathetic. Be wary of labeling sections for beginners. Words like "simply" or "of course" should also be avoided. CSS Tricks has a great article on words to avoid in educational writing.

Writing the post

The writing process varies from person to person. I would suggest trying different things until you find something that works for you. I currently use Notion to write my blog posts. It gives me a place to house my drafts, research, and outline all in one place.

Here are some other tips on writing the post:

Outlines

Use beats to outline your article. Beats are questions that a reader might ask next as they're reading your article. Here's an example of what beats might look like, using the 11ty scenario above.

• What is 11ty?
• What is a static site generator, why is it so fast?
• How do I set up 11ty?
• How do I use markdown to write blog posts with 11ty?
• etc...

Subheadings

Be liberal with subheadings. Subheadings help structure the post and make it easy to skim. Expert readers will probably skim through your subheadings and only pick out the parts that interest them. My subheadings have often followed the next bullet point in my outline.

Code samples

Code samples are hard! Don't feel like you need to add a bunch of depth to a code sample. You don't need a fully working app, you only need something that highlights the problem/solution. Having good code samples is something I still struggle with.

Closing thoughts

All of these more like tools in a toolbox than rules. You don't need to stick to them. Find what works for you! For example, I find it hard to use beats when writing list-type articles. I'll still have an outline, but the outline would look like: intro, list items, conclusion. My final piece of advice: to get better at writing technical blog posts read more of them. Understand why you like them and try to emulate that style in your post. Hopefully, you find these tools helpful. I can't wait to read what you come up with!

---

This post was adapted from my newsletter.

Photo by Florian Klauer on Unsplash