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.
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
Substitute opinions with descriptions
Your assertions are backed up with specific proof
You establish authority somewhere, somehow
You kept the initial promise through which you got attention
(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.
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
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?
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.
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:
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.