Robert Heaton

Software Engineer /
One-track lover / Down a two-way lane

A blogging style guide

06 Dec 2018

Here are 39 ways to make your blog more entertaining to read and more pleasurable to write.

Confidence

  1. Don’t begin by telling the reader why you wrote your piece - tell them why they should read it, and then do your best to prove yourself right.
  2. If you’re wondering whether you should write a piece at all, you probably should. No, the world doesn’t really need another explanation of the Blue-Eyed Islanders puzzle, but by this point it needs very little apart from more malaria nets in sub-Saharan Africa and massive action on climate change.
  3. There’s a three-way tradeoff between establishing credibility, being honest when you aren’t an expert, and sounding like a douche. For example: “No, I didn’t go to writing school. I learned my trade at the University of Life, the School of Hard Knocks, and the physics department at St Catherine’s College, Oxford University.”
  4. If you must self-deprecate then do so in a way that leaves you with a bit of confidence. For example: “Of course, there are many other, much better style guides on the internet than this one, and if you really care about finding and honing your voice then you should just read Elements of Style by Strunk and White. But you’re not reading Strunk and White right now, you’re reading Robert Heaton. You might even have already read Strunk and White, and yet you still have questions, so let’s just continue shall we?”
  5. If you still have reservations about your qualifications to write a piece then state them once at the top, maybe once more at the bottom, and in between forget about them.

Framing

  1. There's nothing wrong with a good old fashioned listicle when you have a collection of points you'd like to make but not the energy or ability to elegantly tie them together.
  2. Many articles begin with a human framing, even those about highly technical topics. Having established a relatable hook, the author quickly moves on to the general point of the piece, before returning at the end to the mid-Western accountant they opened with.
  3. If you don't have a real story with which to frame your piece then consider making one up. For my part I really enjoy discussing online tracking using the Steve Steveington Chronicles and the career of Hobert Reaton, shifty adtech entrepreneur.

Vocabulary

  1. It's fine to use a thesaurus to look up an alternative word for "clever" because you already used "clever" a few sentences ago. Just don't come back with "meretricious".
  2. Make a list of words and phrases you'd like to avoid. For me this includes "For reference", "To give some context", "Like some giant ape". I also don't like the word "folks" unless the rest of your natural vocabulary is similarly folksy too. I'm pretty clearly outvoted on this one, but I still stick with "people".
  3. Unless you have a good reason for swearing, you might as well not. Some people find it off-putting, and I don't think anyone dislikes writing that doesn't have any profanity in it.
  4. Stay away from memes - they're just cliches propagated at the speed of Twitter. Never do anything to "all the things".
  5. It's fine to start sentences with "And" and "But" if you want to.

Style guides

  1. Read "Style: Towards Clarity and Grace" by Williams and Colomb. It's very good. But if you only have the time to read one style guide then well, you're here already, and my one is much shorter.
  2. Choose a few people whose style you like and copy it as hard as you can without infringing on any intellectual property. I aim for a combination of the Economist, Paul Krugman, and Terry Pratchett.
  3. Style guides are useless if you don't practice.

Inclusion and Diversity

  1. Inclusion and diversity level 0 is extremely easy and requires almost no work.
  2. If you need a quick name for a generic fictional character, consider using one from a culture or gender that you usually wouldn't. Even if you don't believe that representation in the media matters, you've surely got to concede that there's still a chance that it might, and that the cost of sometimes calling your imaginary computer programmers Julianna is zero.
  3. "They" is a great word for referring to an unspecified person of an unspecified gender.
  4. Alternatively you can also alternate between "he" and "she" and toss a coin to see who goes first.
  5. Don't be mean about the poor or homeless or uneducated. Southpark and It's Always Sunny in Philadelphia seem to be able to get away with it, but I don't exactly know how and I don't think you should trust yourself to walk their line without falling into a pit of problematicism.
  6. I have decided that I am comfortable with robust but essentially amiable blasphemy.

Humor

  1. Don't let a joke get in the way of your point. You're not writing a standup routine, you're explaining your position on Brexit. I suspect that if you are in fact writing a standup routine then this principle applies double.
  2. If something sounds like the kind of joke or pseudo-joke you might see on an advert for car insurance, reconsider it.
  3. It's better to be clear than funny.
  4. It's entertaining to poke fun at the downsides and pomposities of capitalism without necessarily denying the fact that strengthened property rights appear to have been responsible for much of humanity's progress in the last century or two.

Metaphors

  1. Don't let a desire to be (or at least sound) literary get in the way of your point.
  2. A light extended metaphor can help your reader remember an idea, even if they didn't need the metaphor in order to understand it.

Miscellaneous

  1. Be sparing with pronouns in technical writing. It's better to repeat a noun than have it be unclear what "it" refers to.
  2. Your post should ideally still work without hyperlinks. It's useful to include them for additional color and context, but lazy and unhelpful to rely on them.
  3. If you could easily make your piece and website accessible to people using a screen reader, then why not do so? GitHub has some simple guidelines that I try to follow.
  4. You can often make a piece much clearer simply by reordering the words in its sentences.
  5. Don't bury the lede. You're not writing a thriller, and you should rarely build towards a big reveal that the reader realizes they should have seen coming all along. Prefer to instead state a conclusion, then demonstrate why it is true.

Process

  1. It's fine to spend 10, 20, 30 minutes staring into space when your plan for the day says that you're meant to be writing.
  2. It is admittedly even better to spend that 30 minutes spamming down any old nonsense that you can refine later, or that at least helps get you mentally unblocked.
  3. But it's much worse to spend 10, 20, 30 minutes staring into space and then feel bad about it.
  4. If in doubt, reduce the scope of what you're trying to write about. Your first 3 points are probably already interesting enough on their own.
  5. If you must write a part 2, try to make it also work as a standalone piece.
  6. Try not to let yourself realize when you start writing your final draft. It often becomes much harder to write or change anything for fear of getting it wrong.

This post has been translated into:

Subscribe to my new work on programming, security, and a few other topics. Published a few times a month.
Follow me on Twitter ➜ RSS ➜