

A checklist for improving the writing style of technical blog posts - ppolsinelli
http://pietro.open-lab.com/2010/02/23/improving-the-writing-style-of-technical-blog-posts/

======
thaumaturgy
I thought this was a pretty neat example of irony. His title is "Keeping It
Brief", but I noticed the wide format of the text coupled with the scroll
indicator on the right, and I was a little horrified. This is brief?!

Not one to be intimidated by voluminous text, I began to read anyway, and
found in the very first sentence: "Why few blogs are very popular, and most
practically ignored?" ...Well, I dunno, why tiger run?

So, now I'm faced with the prospect of reading a large text which the author
apparently didn't even bother to proofread. Oh joy. My well-honed, internet-
trained skimming instinct kicks in: _skim skim skim_ Write like Joel _skim
skim skim_ Write like Jeff _skim skim skim_ Write like Seth...

Where in the hell is the actual checklist? Why not let it speak for itself?
Oh, wait, here at the very bottom. OK, so what's on it?

Well, the same generic, overgeneral tired stuff that every mediocre writer
keeps saying, that's what. It even comes with the arrogance to suggest that
you might want to download it in PDF.

Try this instead:

1\. Is it brief?

2\. Can you remove anything else from it, especially stuff that the reader
will find completely useless? (Example: "I read many blogs for professional
reasons, and some among these are a real pleasure to read." The reader doesn't
care about what you read, or why. Strike it out.)

3\. What are you saying? Are you giving the reader useful information? An
insightful story? Or are you just trying to keep your tired blog "fresh"?

4\. Did you make your point clearly?

5\. Did you check your facts? (Your article _does_ contain facts, doesn't it?)

6\. Did you proof-read it? Twice?

7\. Did you get a friend to proof-read it?

8\. Did you break up your paragraphs whenever possible?

9\. Have you reviewed and used basic typographical rules, like those outlined
in [http://www.smashingmagazine.com/2009/04/03/8-simple-ways-
to-...](http://www.smashingmagazine.com/2009/04/03/8-simple-ways-to-improve-
typography-in-your-designs/) ?

~~~
morisy
Good advice, reminded me of K. Vonnegut's list:

1\. Find a subject you care about

2\. Do not ramble, though

3\. Keep it simple

4\. Have guts to cut

5\. Sound like yourself

6\. Say what you mean

7\. Pity the readers

Source, "How To Write With Style": [http://peterstekel.com/PDF-
HTML/Kurt%20Vonnegut%20advice%20t...](http://peterstekel.com/PDF-
HTML/Kurt%20Vonnegut%20advice%20to%20writers.htm)

------
ezyang
I started blogging recently (the start of the new year, actually), and it's
been quite interesting watching the analytics bounce up and down depending on
what I've posted that Monday/Wednesday/Friday.

Perhaps the most striking thing I've noticed is that when I blog about
Haskell, I get a lot of hits. :-) Perhaps that says something about the
importance of keeping audience in mind.

As your standard egotistical human being, I'd love to increase readership.
That's a great validation for me. But it definitely means that you have to
write about more popular/accessible subjects. And there's a lot more
competition there.

------
grumpyfart
It doesn't matter how to be popular, let's not forget the power of being a
hardcore technical blogger who only have few visitors (but awesome followers).
Blogs that only a few can read and understand. There is nothing wrong with, we
can't expect that every niche blog will have millions of visitors.

If you want to be popular choose popular topics, explain them in the most
clear (KISS) way, then keep doing it. Now and then post a blog with some
religious stuff in it. Post obvious stuff but, put lovely pictures, cure
kittens and try to explain one simple thing like no one knows it.

Unfortunately more and more blogs are getting empty, good stories, lots of
bollocks but not a damn real thing, or the same things over and over with a
new narrative...

So please, please, please don't improve your technical writing style to be
"yet another 'I write nice blog posts about mass technical(ish) people'
blogger.

No offence to Joel or Jeff, they are doing something nice, but we don't need
more Joels or Jeffs, that area already have been covered.

Write pure technical blogs and deep subjects if you dare, not stories.

~~~
compay
"No offence to Joel or Jeff, they are doing something nice, but we don't need
more Joels or Jeffs, that area already have been covered."

Sorry, but that's simply terrible advice. That's like telling Kafka, "don't
write your short stories, Poe already has that style covered."

I agree we don't need a bunch of lame Joel/Jeff knockoffs. But we certainly
shouldn't discourage people from trying to stand on their shoulders to create
something better.

~~~
grumpyfart
You got a good point, let me retry:

We need all kind of technical bloggers not only Joels and Jeffs :)

------
gilesbowkett235
people, this is ridiculous.

 _Why few blogs are very popular, and most practically ignored?_

the first sentence isn't even grammatical.

~~~
michael_dorfman
Sure it is. It uses a common trope; the omission of the repetition of a verb
in a pair of yoked clauses is called "zeugma".

~~~
derefr
He's talking about the relative position of the word "are", I think.

