A checklist for improving the writing style of technical blog posts (part two)

This blog post is the second part of a previous post, Improving the writing style of technical blog posts. Read the first part before proceeding.

As you survived reading up to here, now you get a reward: a simple checklist which you can use to verify your posts before publishing them. The checklist does not contain anything about the core quality of your contents: being a technical writer / worker, it is simply assumed that you have something of value to say, but don’t know exactly how.

Checklist

(Get attention)

  • There is an effort to capture reader’s attention in the title and very first sentence

    Copy is never too long, just too boring.

  • Benefits for the reader are immediately clear – instead of features

    I woke up this morning thinking: I really need …

  • At least in the first paragraph, every sentence somehow leads to the next one.
  • The post contains a (short) story

    “For sale: Baby shoes. Never used.” Ernest Hemingway

(Authority)

(Style & format)

  • Can you make it shorter? Where in doubt, cut it out
    “To be or not to be?”
  • You kept the language simple and clear.
    No one will ever complain that your writing is too easy to understand.
  • You sum the contents up at the end of the post.

(Review)

  • You’ve printed the draft on paper and re-read it

    A way to get a new perspective, a bit like giving it to someone else to read it.

  • You read it loudly

    A way to become sensitive to the rhythm of your writing.

  • Immediately before publishing it you did spell check it not just on some online spell checker but on Microsoft Word.

This is it. Shouldn’t be too hard. Download here the checklist in PDF format.

One could add to this list, with a slight change of focus, “Did you insert meaningful SEO words?” in your writings – but this opens up further considerations, maybe I will discuss them in a following blog post.

Using these techniques

Am I using this checklist? Well, I am. Consider for example this recent blog post I published in one of the most boring blogs on the web, the one where we announce Teamwork’s releases:

There were once two brothers and a sister, and they were managers at three companies.

The first brother was called Micro Manager, and he picked the most complex  […]. And after a week everybody hated the system, and then they hated Micro Manager, and everybody was unhappy.

The second brother was called Over Simplify, and he didn’t want any kind of management apart from to-do lists […]. And then they hated Over Simplify, and everybody was unhappy.

Their sister was called Reasonable Modesty, and she had minimal goals, had always clear that what matters is how people work and interact, and that software is always secondary, and should be flexible, not do too much, and not get in the way. She started evaluating Teamwork.

Teamwork’s blog usually has posts like “Teamwork 4.3.12323 released”, followed by say a series of bug fixes which make sense only for Teamwork administrators, and can be made more interesting (and popular) using the techniques just described. In fact many people liked this last one.

Another example, this very blog post: this is a bit particular as it is half way between a guide and a blog post, some call it a “blogzine” entry. I did review it (several times) according to its own criteria, and made many changes (improvements, I hope).

A well-written blog post can have several “usages”:

  • It can be used as a base for a talk for a conference – or for proposing one
  • It can become a chapter of an e-book
  • It can be the base for building the contents of a dedicated micro-site
  • It can be transformed in a project – for example as done at the Startuptodo service

Again, all contents of good quality have a positive SEO effect: it is a side effect, but it can be great.

Exercise: review your latest blog post with this checklist. Is there anything that could be improved?

Conclusion

So we started from examining the writing and narrational style of some popular technical blogs, and then isolated a few techniques in a checklist which you can use to refine your own blog posts. This is just a start, you can find references and more material to study in the next section.

Further reading

I would like to thank Mr. Brian Clark for his brilliant site, copyblogger, that I discovered half way through and gave me a host of new ideas. Some advice on how to write blogs is at the end of this podcast:

http://blog.stackoverflow.com/2010/01/podcast-81/

From the notes:

Some tips from Joel and Jeff about why and how (or if) programmers should blog. Set a schedule and stick to it. And don’t be a commodity blogger! It helps to focus on the storytelling aspect of the writing, per Ira Glass. And remember, writing a better article on any topic is usually pretty easy, because so much of the content on the internet is so darn bad.

The Delicious links provide some sources.

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

Comments
5 Responses to “A checklist for improving the writing style of technical blog posts (part two)”
  1. FuManChiu says:

    Fantastic checklist! Not by any means brief, but fantastic nonetheless!

  2. I will add to points to my own list: answer two basic reader’s questions in order to get some trust: who are you? Why are you writing?

Trackbacks
Check out what others are saying...
  1. [...] comment « The blurring distinction between graphic design and software development A checklist for improving the writing style of technical blog posts [...]

  2. [...] A checklist for improving the writing style of technical blog posts (part two) [...]

  3. […] post about “A checklist for improving the writing style of technical blog posts (part two)“  also useful to read before we publish our […]



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com 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

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: