Anatomy of a Blog Post

These are the bits that going into making up one of my blog posts. I make decisions on each of these points and create something that is hopefully useful and satisfying to me and an artifact to share that others might draw inspiration or help from as well.

Types of Posts

I divide my writing into two kinds of posts: technical and non-technical thoughts.

The technical post are recounting how to do specific things. They are usually step-by-step instructions. They help me remember things important to me. They are useful to others as we often follow similar technology paths.

The thought posts are just things on my mind. It's more free prose. These are the things that I've been contemplating and consider of some importance. Hopefully these posts can inspire others to create better lives for themselves as well.

Choosing a Title

If I'm writing a technical post, I usually choose one that matches what my Google search term would be when trying to accomplish the task as I see it. It's usually good for SEO and clarity.

If sharing my thoughts, I usually use something more abstract. I like something with some whimsy, often hinting at the subject. Having something to discover can be fun to read and to write. Sometimes I draw rather tenuous connections here between the title and the subject content.

Saving some Meta Data

Meta data for the post usually consists of those things that help in blog organization or Internet discoverability.

Category

Mapping well to the types of post I write, I currently assign posts on my site to 3 categories: "Code" (technical), "Leadership" (thought), and "Book". (I also record short summaries and sometimes reviews of the books that I read on the site.)

The "Code" category is vast but easy to categorize. The "Leadership" category can be about any number of things: soft skills, productivity, communication, teamwork, or culture, etc.

Tags

I define a few tags for the post. There is usually an attempt to reuse tags that are already on the site. There is a view for reading posts one tag at a time. I hope that this helps enable readers who are interested in a certain theme.

A few recent tags are: js, react, environment, productivity, rest, tdd, testing. You can browse all the tags yourself.

Description

This is a short summary that appears in the Google search results. It supports the title. It is usually one sentence, maybe two, that clarifies the content of the post and encourages reading.

Making an Introduction

The intro is a slightly longer restatement of the description. Sometimes it's an exact copy. I try to include the "why" of the post if it's not obvious. This is the value statement, telling why the reader should read more. It often includes the essence of whatever thought or tech I'm about to explore in the post.

Choosing Headings

I use headings to group my thoughts. I like encountering these in articles that I read. They help lead my mind through the aspects of a subject. For me, these usually grow out of my outline or notes. Sometimes they're a chance to turn an phrase. Other times I'm thinking of SEO help when I choose my headings.

Headings will group my related thoughts or label the next set of steps needed to accomplish a technical outcome. There are usually just a few paragraphs per heading.

Finding My Voice

I try not to be another whining, complaining voice on the Internet. I want the post to sound positive and fun. Many companies purposefully avoid the silly. I am embrace it.

If the topic is objective, mostly technical, using "you" in the text feels quite natural. "One" usually feels too formal for me. If I'm expounding on a topic that's a more touchy-feely, I try to use "we" when addressing the reader. I don't want to be too preachy, and I want to include myself in prose and in practice.

Most of the time I try to write like I talk and just let it -- flow.

Creating Code Blocks

Essentially all my technical posts include code blocks. This is often my favorite part of technical blogs that I read when I'm trying to figure something out.

I try to keep the code short. I often draw from code I've written lately in real life or I sometimes make up something (that I hope visually compiles) on the spot. I take time to remove cruft in order to expose the essence of the concepts. If the code is not short or is dense with concepts, it usually has to be followed with lengthy explanations. To keep these more terse and scannable, I sometimes use bulleted lists to organize these.

At Length

My goal for a post is to have the final length about 500 words. I believe that people lose interest after that. Maybe I should say we lose interest after that. I have lots of posts that are longer, probably in the 600-900 word range. I have some that are much longer. Most of those are long technical processes. You might find me pontificating about some other topic too. To get a post this short, I try to remove rambling sections, repetition, and edit for precision.

Conclusion

My conclusions are usually quick. They wrap it up by restating the essence of the intro really quickly. Here's what we should have learned by reading this.

I try to end with a question. My hope is that this keeps the conversation going. It is an attempt to get the reader to reflect on and apply what they've been reading to their own situation. This is especially important in the thought pieces. It's also an invitation for those readers of technical posts to share their own solutions.

Banner

The banner is visually interesting, which I like. It's an opportunity to bring more fun into the post. It allows me a chance to do some illustration, which I enjoy. It's often another place to include some abstract allusion to the subject.

And that's it. I get those bits onto the page and ship it. If you're interested, I can share a bit more about my process in getting to those bits. What are the things that you include in your blog posts or your approach that you find helpful?