A Starting Point for Writing Technical Blog Posts

I've accumulated a lot of useful info as a front end developer over the years, and want to be able to share that with others. Unfortunately, teaching doesn't come naturally to me. I feel like I need to simultaneously know everything and teach everything all at once, which of course is impossible. I also have a hard time narrowing down what the most important concepts are because everything seems equally important to me.

When I decided to try writing a technical blog post, I searched around to see if there were any guidelines or best practices I might be able to follow. That's when I came across howtoegghead.com, which is a guide for egghead.io instructors on how to create lessons. I found it really helpful, and highly recommend reading through it if you're looking for guidance.

Here's a summary of the points I found most useful (adapted for blog posts), plus some of my own thoughts. Full disclosure: this is all new to me, and mostly just notes to myself as a way to encourage myself to write more.

Decide what to write about

Some ideas for topics:

• something you're passionate about
• something you've learned recently, or are in the process of learning
• something you've figured out recently (e.g., a confusing bug or unexpected edge case)
• something that seems super simple to you, but might be a big help to anyone less experienced

Make sure to narrow this down to something very specific. It should be something you can talk about in just a few minutes. For example, my thought process might be something like this:

• I'm passionate about accessibility, so I should write about that! - This is way too broad. I wouldn't even know where to start.
• Being able to use a keyboard to navigate a website is important. - A little better, but still too much to cover.
• The first thing I notice with keyboard navigation is how important it is for focus states to be visible and easy to spot. - Much better. This is finally something I can start wrapping my head around.
• I'll talk specifically about button focus states. Perfect! This sounds pretty simple on the surface, but there's a lot I can talk about.

What I love about this is that I could potentially write a series of short, related posts that each go into detail about one specific thing. It gives me permission to leave out extra details that I feel like I should mention, but don't necessarily contribute to the current topic.

It's totally fine if you want to write about something that other people have already written about. By writing in your own words, you're giving people another viewpoint that might make things click. It's also a great way for you to reinforce what you've learned, and for your future self to reference.

Some of my favorite blog posts are ones that cover the absolute basics of HTML and CSS. These are things that have been covered many times already, but I always learn something new.

It doesn't matter if you're a beginner. If you're a beginner, you might work through things in a way that makes sense to other beginners. Someone more experienced might include a code snippet without explicitly stating which file that code is supposed to go in. Or they might include something to run from the command line without explaining that you first need to be in the right working directory. Those are the types of things I get stuck on when I'm learning something new, and they're usually hard to figure out when you don't know how things work yet.

Be clear and to the point

Assume your readers already have the required background knowledge. If there's anything they don't know, they can look it up on their own.

Don't include an intro, outro, or stage-setting. Think about when you search for a recipe and have to read someone's life story before you find the ingredient list. We want to keep it simple, so include only the content people are looking for.

Show your work

Include a series of editable code examples. It's one thing to read about something, and another to see it in action. Instead of describing everything in words, use code examples to prove your point. Here's an example of what I mean:

By including a series of examples, readers can see each step of the process and how it affects the result. And since these can be edited, readers have the option of playing around with the code to get a better understanding of how things work.

Now you're ready to write!

I put this together because I was having a hard time getting started without a list of guidelines to follow. Now that I have a starting point, I'm hoping it will help make the writing process easier for me in the future.

Are there any resources you use to figure out what to write about or how to structure your posts? Or do you have a specific process you like to follow that works for you? I'd love to learn more about how others are doing this!

One thing I found after writing most of this was Ali Spittel's blog post workflow which goes more in-depth - would've been helpful if I'd noticed that first! 😉