Improving the writing style of technical blog posts (part one)

Why few blogs are very popular, and most are practically ignored? You may believe that popularity is simply a question of luck or money. I read many blogs for professional reasons, and some among these are a real pleasure to read. Well, it also happens that the well-written ones are the most popular among the ones I read, and being well written may be what explains their success, at least partially. So in what follows I do some analysis of writing styles and then define a checklist which you may use to analyze your own blog drafts before publishing them, eventually improving your writing.

Most popular blogs are “well written”: by this I don’t (just) mean grammatically correct, I mean well written by looking at them as sort of short stories. Looking at blog posts in this way is a perspective that probably escapes technical writers; it is obvious for anybody who has copywriting experience. A blog can be very well written and not be popular, and there may even be popular blogs that are badly written, but there seems to be enough correlation with “good writing” for blogs that have contents as good as those of many others but stand out in popularity.

Now we will examine three popular blogs, to see some writing techniques in action. Then we will try to define some rules to improve your blog’s writing.

I will not go into why having a popular blog can be important, I just assume that it is so – a discussion would lead us to an entirely different topic. What is here said about writing is contextualized to blogs, but I believe can be a help in any kind of copywriting activity.

Three popular blogs

The blogs I’ve chosen as examples are those of Joel Spolsky, Jeff Atwood and Seth Godin. The first two are about programming,  the work of programming and software marketing, the last one about marketing and spreading ideas.

Joel On Software

As an example post from Spolsky’s blog I’ve picked this one: The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!), and here is a short abstract from the blog, the opening paragraphs:

Ever wonder about that mysterious Content-Type tag? You know, the one you’re supposed to put in HTML and you never quite know what it should be?

Did you ever get an email from your friends in Bulgaria with the subject line “???? ?????? ??? ????”?

I’ve been dismayed to discover just how many software developers aren’t really completely up to speed on the mysterious world of character sets, encodings, Unicode, all that stuff. A couple of years ago, a beta tester for FogBUGZ was wondering whether it could handle incoming email in Japanese. Japanese? They have email in Japanese? I had no idea. When I looked closely at the commercial ActiveX control we were using to parse MIME email messages, we discovered it was doing exactly the wrong thing with character sets, so we actually had to write heroic code to undo the wrong conversion it had done and redo it correctly. When I looked into another commercial library, it, too, had a completely broken character code implementation. I corresponded with the developer of that package and he sort of thought they “couldn’t do anything about it.” Like many programmers, he just wished it would all blow over somehow.

Notice how this blog post, which is highly technical, start by asking questions and telling short stories – I’ve underlined the starts. And not only is the beginning like that, it keeps proceeding in such fashion. Why don’t you go now and read it, trying to notice the short stories that pepper this nice post.

Coding Horror

Coding Horror- The Great Newline Schism_1266418517767 Let’s examine now Atwood’s Coding Horror blog, for example this blog post: The Great Newline Schism. The topic of this  post is newline invisible characters, and this post  topic is probably on one of the most uninteresting topic ever, but reading it is a pleasure anyway because of the way Atwood evokes old typewriters and nice pictures to lead the reader along; he is not telling a story in a classical sense, but he is indeed engaged in narration:

“The Carriage Return (CR) and Line Feed (LF) terms derive from manual typewriters, and old printers based on typewriter-like mechanisms (typically referred to as “Daisywheel” printers).”

Seth’s blog

Finally, let’s consider the posts from Seth Godin’s blog: these are short (yes, mine aren’t :-D).

Consider The hidden power of a gift:

“Perhaps we resolve it, as the ancient Native Americans did, by acknowledging the power of the giver … The key is that the gift must be freely and gladly accepted”

and Frightened, clueless or uninformed?

“Comfort the frightened, coach the clueless and teach the uninformed.”

His posts are filled with anthropological observations: he manages to link to the readers’ emotions. He has a talent for finding latent emotional roots in apparently purely commercial / economical interactions. He looks at human beings as emotional chimpanzees – which you may say is exactly what we are – and as shaped by implicit social norms; we are not as logical as we’d like to think we are. Seth explains behavior through micro anthropological narrations, which take little time, and stimulate reflecting on the bases of motivation – hence on marketing.

How To Hack Your Brain, Part 1- Sleep - Dustin Curtis_1266916351269 Design for beauty or readability?

The communication strategy which we are trying to refine here is focused on narration, as this is a way to transmit contents. A different strategy is to use design, but then it will be much harder to communicate a specific content; you will need a different design for every post, and find / invent a graphical metaphor. This is what indeed some talented designers are doing: see

These are incredible designers that create a different design for each blog post. But as said above, our idea is to excite the reader with narration, not with novel design, as we want the reader to focus on contents. So pick a simple, highly readable, consistent layout for your blog and stick to it. Use very simple typographical tricks to lighten the reading experience, and few pictures.  For an example, consider Joel’s clean style. Don’t invent a layout – its non trivial!

The importance of a good start

Blog titles play a crucial role in your posts, similar to that of product / web site’s pitches. What is the purpose of the pitch – in our case, of the title? The purpose of the title is to make the first sentence read. And what is the purpose of the first sentence? The purpose of the first sentence is to make the second sentence read. And so on: if you don’t get the attention of the visitor with the title, your failure is complete.

So make sure you try lists of different titles and starts, and variations on them. Get someone to verify them with you. Do the titles and openings grab attention? Interest?

The words that you are choosing there are important too: these should be inspired by the words used by your potential visitors / customers to describe their wishes, hopes, desires, dissatisfactions, fears, worries in relation to your topic / product.

You should probably dedicate almost half of the total time you dedicate to the post’ writing to experimenting with the title and start. For example, in the case of our Patapage site it took me months to get to a decent pitch. A blog post title is somehow less important than a home page pitch, but still put a significant part of your effort on the opening.

Raising money for StackOverflow - Joel on Software_1266407825138 Why telling stories is good idea?

First you should realize that “by default”, nobody is interested in your blog posts, apart from very few people close to you who maybe, maybe, are interested. This is so important to deserve repetition and bold fonts:

nobody is “spontaneously” interested in what you are writing.

This is a “negative” truth. But here comes a “positive” one:

people are hungry for stories.

These two facts can help all along your writing.

As a technician, you are probably the least apt to communicate to the general public, and you also have to communicate the hardest topics. Furthermore, what you are trying to say cannot be trivialized without losing its essence. If you explain your ideas in technical terms, it will be non trivial to keep the attention of the readers. This is why using stories is a good idea: you can begin communicating non trivial ideas building up the readers’ attention.

So tell a story. Now, not a silly story: the point is not telling jokes, the point is to introduce your topic.

The conclusion is: in your post, tell stories, about conflicts, experiences, problems leading to your theme, and you’ll get the reader’s attention.

Hiring a copywriter may not always be the solution

If you are working with a large budget, the simplest way to solve any copywriting problem like writing good blog posts is simply to hire a copy. With the web and social media opening “windows” on companies’ activities, many (most?) companies actually need to create well written, interesting contents every day of work. Now, can you hire a full-time copy? If you can’t, like me, you can do a lot by yourself.

As a startup, there are several occasions where we got perfectly good solutions with a little internal research instead of paying expensive consultants with dubious competencies. The “solution” hire a consultant simply assumes that consultants are competent by default, which is often not the case. Need to write a license? Need a user guide? Need SEO optimization? Hire an expert. We didn’t, and are happy with the results; again, these problems appear continuously, so you need the relative competencies in-house.

In order to write, you need to have some “creative spirit”. It is impossible to learn to be creative: Steve Jobs as quoted in Inside Steve’s Brain says that seeing people trying to become creative is “painful to watch”. Indeed it is. Here I’m just assuming that you are, and that maybe your attention needs to stop a bit on your own writing style.

And now… go to the checklist!

This blog’s theme is discussed on Twitter and classified in Delicious under the tag “wellWrittenBlog”. The second part of this blog post, “A checklist for improving the writing style of technical blog posts” can be found here.

7 Responses to “Improving the writing style of technical blog posts (part one)”
  1. mschoeffler says:

    Nicely analyzed, nicely summarized. Great writing, Pietro.

  2. gsempe says:

    Great post.
    Storytellers have the power till the beginning of human beings. It’s always true.

  3. John McLean says:

    Thanks for the direction and inspiration!

  4. bellatx says:

    I interpret via google translate – provision up with the updates !


Check out what others are saying...
  1. […] by Pietro Polsinelli on February 23, 2010 This blog post is the second part of a previous post, Improving the writing style of technical blog posts. Read the first part before […]

  2. […] has published a blog post on Improving the writing style of technical blog posts. Categories: Conferences, General interest, Web marketing Comments (0) Trackbacks (0) […]

  3. […] Compiling the result, I found many and take 2 sources, they are blog post from Matthew Skelton who write HOW TO WRITE GOOD TECHNICAL BLOG POSTS , and Pietro Polsinelli who write Improving the writing style of technical blog posts (part one). […]

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: