Writing a Technical Blog

I wrote about how I structure my writing in general last November, as part of the 14,584 words I wrote for Virtual Coffee's blogging monthly challenge. This will be my 14th blog this November, and I found myself reflecting on how I get my ideas and turn them into published technical blogs.

Ideas

Anytime you solve a problem or learn something new is great time for a blog. Write a blog when you:

• Explain something to a coworker
• Finish a big feature at work
• Dive down a research rabbit hole
• Want to research something so you understand it a little better
• Build something just for fun
• Want to take detailed notes on something you just figured out

Once you have your idea, decide if you're making a guide or reference.

Guide

A guide takes the reader through building or doing something step by step. If you want to make a guide, there a few questions to ask yourself:

• What skill level am I writing for?
• What knowledge does the reader need to understand this?

You want to open the blog by declaring any prerequisites. This prevents you from having to explain every single concept you use. For example, if you're building something in React, say "This blog assumes you are familiar with React."

Next, ask yourself, what is square 1? What is a completely blank slate? Start the instructions there.

Blocks of code visually break up text, which is good for moving the eye along. However, don't expect your code to explain itself. It's like explaining a problem and its solution to a coworker - you need to give context. This includes names of files, if your code spans multiple files.

Reference

A reference article explains or teaches a concept. Rather than step by step instructions, you want to focus on summarizing an idea. I start by making an outline with headings.

As I start to describe a concept, I usually realize there's more I have to explain. That means adding headings to my outline or even breaking it out into a whole new blog.

The opposite of a guide, reference blogs quickly get dense, so it's important to break up the text. I use headings and memes.

Editing

Leave it sitting for a day or two and come back and read the whole thing, out loud. You'll be surprised what typos you find. If you can get someone else to read it for you and give feedback, even better.

In rereading, I often find I've used a word a lot and have to reword sentences. "Often" has been one of them recently.

I'll fine-tune explanations and be more explicit about how concepts relate to each other. With guides, I'll follow the steps myself.

Conclusion

Anytime you want to understand a concept a little better, explain it to someone else. Technical blogs are a great way to help yourself and others learn at the same time.