How to write good blog posts: my personal guidelines

Image courtesy of NASA Commons

Hello and welcome to my post on how to write good blog posts. I first wrote this in July 2015, but I last updated it in Feb 2019. Writing well, blog posts and otherwise, is an important topic for me, so I’m going to update this post for years to come, as I keep getting better at writing and blogging.

What do I mean by “good”?

There are many dimensions and layers to a good blog post. I can’t concisely focus on them all. Therefore, I want to focus on just one overarching goal for my writing, which is:

A good blog post has useful content, strong prose styling, and conveys some “realness” about the person who wrote it.

My overarching goal in blogging

If I can meet this goal, I believe that the other aspects (clarity, structure, etc) of a good post will fall in place over time. It might take me a few rounds of edits to get there, but I know where I’m heading.

Does this apply to all blogs?

My goal, and the guidelines I use to reach that goal, are stated broadly. They don’t imply any particular kind of blog.

That said, I generally don’t read blogs recreationally. Most of my leisure reading focuses on good ol’ books, magazines, and newspapers, albeit usually in digital form. Overall, I believe that blogs complement, rather than replace, those forms.

Rather, my main use of blogs is utilitarian. I look for blog posts to help me answer questions or figure out how to do some particular thing. As a professional software developer, I often look for “how to do X with code”. These days, the answer is usually found on Stack Overflow. However, ten or more years ago, much more of this information was on blogs.

Nevertheless, a utilitarian post is still a piece of writing by a person. Sure, my first priority is to answer my question or learn about some topic. But I am also interested in learning more about the person who wrote it. When it comes to software developers, I have found very few that are strong writers and express themselves as such, but there are notable exceptions, such as objc.io and Steve Klabnik.

Enough jibjab, get to the guidelines already!

Without further ado, here are my 5 guidelines on how to write good blog posts.

1. Be Yourself

Is it easy to convey your “real voice” in writing? If it is for you, fantastic. For me? Nooo.

In my experience, writing well is hard, and takes deliberate effort and practice to get better at. How you speak is often quite different from how you sound in writing (unless you are Seth Godin). Of course, your spoken and written voices will invariably differ. But most people are better at conveying their personality in everyday speech. The goal is to capture enough of that personality in your writing so that the writing reflects who you are.

And exactly how do you convey your personality in writing? There’s no single answer. Your personality is expressed by the kinds of stories you tell, the examples you highlight, word and idiom choice, etc.

Much of the world, billions of people, are on the Internet. Many of them write on Facebook and Twitter, and probably millions have active blogs. Therefore, chances are good somebody else is already writing about the same topics as you. However, rather than see this as a competition, consider it a chance to see the same topic from different viewpoints. That makes the world richer in content, rather than fiercer in competition.

2. Be Personal

Being yourself and being personal go hand in hand, but I keep them separate for emphasis. There are subtle differences to consider.

When I say “be personal”, I am not suggesting that you should divulge private details and the like. Privacy is important, and you should be aware of and in control of your own digital privacy choices.

Some people do choose to write online about very private topics, such as depression, grief, serious medical issues, etc. I’m sure it’s cathartic for some people to share these stories and for others to read them. However, the Web is an open medium. When you post anything online that is not anonymous, you must weigh the benefits of contributing to an open Web, with the risks, such as being hounded by vicious Internet trolls. Furthermore, true digital anonymity is really hard to get right. So be careful.

So, when I say “be personal”, I mean: focus on being authentic, sincere, and write from your lived experience. When done well, such writing can be fascinating, regardless of topic, and will resonate with many different kinds of people.

How can you be personal without divulging too much? This depends on the personal stories or topics you choose to write about. Nevertheless, you can be authentic and sincere on almost any story or topic, by using the right tone, nuance, and level of transparency.

3. Be Thoughtful

When you are talking to someone in person, it’s easy to “think out loud” and share half-baked ideas. The other person might be a close friend and understand the context, and help you refine your thoughts, play devil’s advocate, suggest alternative viewpoints, etc.

However, on the Internet, you don’t know your audience. You don’t know who is going to read your writing. Hasty, unsubstantiated ideas can be turned against you and used to mischaracterize or even defame you. Thus, being a responsible writer on the Internet requires being thoughtful in what and how you write.

One way I improve the thoughtfulness in my writing is by focusing on logical rigor. Good conclusions follow from strong, substantiated premises. Weak premises lead to faulty conclusions.

On the other hand, don’t take logical rigor too far and be some impassive Spock-like figure. What I really mean is: think deeply and carefully about what you say, do a responsible amount of research, and write in such a way to capture both what you are saying and why you are saying it.

Furthermore, focus on constructive efforts. It’s easy to poke holes; it’s much harder to disagree respectfully and offer credible, realistic alternatives.

4. Examples, examples, examples

Being yourself, being personal, being thoughtful: these all benefit greatly from examples!

Show, don’t tell. Especially when writing about software development or other practices that don’t lend themselves as readily to compelling, Moth-worthy stories. Joel Spolsky said it well in one of his classic articles:

The author had violated the number one rule of good writing, the “Show, don’t tell” rule. There was not a single story in the book. It was chock full of sentences like “A good team leader provides inspiration by setting a positive example.” What the eff?

Joel Spolsky, Introduction to Best Software Writing I (2005)

What’s more, on today’s Internet, it’s so easy to find examples—there’s almost no excuse for not doing it! Way back in the day, you had to go the library to find books or “encyclopedias” or old newspaper and magazine articles (on microfilm no less), then make photocopies, etc. Now, you just search and follow links. Factual? It’s usually on Wikipedia. Recent? It’s probably in your social media feed. The Internet doesn’t have everything, and Wikipedia and other sources are not perfect, but the examples you can readily find are often good enough to get the ball rolling.

5. Edit as Needed

The beauty of the Web as a medium is that you can edit as needed, five minutes or five years later. The beauty of editing is that it lets your writing become more you, more personal, and more thoughtful over time. You don’t have to “get it right” the first time you publish. Of course, you don’t want to be horribly wrong the first time either, but if you get the core idea right, you can iron out the details later.

That said, perfect is the enemy of good, so don’t let the opportunity to edit ad infinitum over-trigger your perfectionist tendencies. I usually let months or even years pass before editing an old post. But when I start editing, it usually takes me days of effort, and dozens of revisions, until I am happy with the new version.

Do these guidelines really work?

These guidelines are my North Star. I refer to them when I write new posts and when I edit older ones.

However, these are guidelines, not a straitjacket. When I write a new post, I focus mostly on getting the core idea right, and I check to make sure I haven’t gotten anything else egregiously wrong. As this article’s headline puts it, it’s about having a Bias for Action while avoiding the Oops Factor.

Furthermore, when I edit my old writings, I consider these guidelines even more carefully. The rush to get something published is over, so I can focus on quality.

In Conclusion

These are my guidelines on how to write a good blog post. And now for a parting quote:

I am for richness of meaning rather than clarity of meaning; for the implicit function as well as the explicit function. I prefer “both-and” to “either-or,” black and white, and sometimes gray, to black or white. 

Robert Venturi, Complexity and Contradiction in Architecture (1966)

Last updated Feb 2019. You can find older versions of this post on Github. And tap/click here to leave a comment. Featured image courtesy of NASA Commons.

OK Medium, you win. For now.

Note: This was migrated from my old Medium blog. I have decided to migrate from Medium to WordPress, and I’ll write about the reasons why soon, stay tuned.

Call me old school, but I believe that a personal website is an essential part of your identity on the Web, a necessary counterpoint to the curated social media game (Facebook/Instagram, Twitter, etc). For coders, a canonical example is Jeff Atwood’s codinghorror.com.

I made my first personal website in 1998. I can’t even remember anymore if I hosted it on the college intranet or actually had a domain name. Really, I just wanted a motivation for making graphics in Photoshop. There wasn’t much real content. I’m no Jeff Atwood.

The current incarnation of my personal website is very much like punctuated equilibrium. I’m still no Jeff Atwood.

Despite my fondness for that particular form of unrealized ambition, I have decided to use Medium as my writing platform. Maybe one day I’ll repatriate, but for now I will write here.

The reasons for this decision are twofold:

  • I don’t have the time or overwhelming inclination to tinker with self-hosted blog platforms (WordPressGhost) or brain-involving static site generators (Jekyll), SEO, etc. My current website is basically static HTML constructed using the simplest generator I could find, harp.js, basically to preprocess includes.
  • I buy the argument that Medium can get my writing in front of more eyeballs, relative to the reach of my personal website in the absence of massive and tedious (for me and you) self-promotion (e.g. constantly tweeting links).

And the funny thing is, Jeff Atwood even explained how to become Jeff Atwood. Read it here, but here’s a teaser for starters:

I don’t care if you have nothing interesting to say. If you can demonstrate a willingness to write, and a desire to keep continually improving your writing, you will eventually be successful. — Jeff Atwood, How To Achieve Ultimate Blog Success In One Easy Step (2007)

That’s simple, sincere, good advice. So really, as much as I love the personal website as a thing, the more important thing is to take the path of least resistance towards writing more frequently. And that’s why Medium wins. For now.

Originally posted on 4 July 2015. Revised 27 May 2016, and again on 5 January 2018.