A blogging style guide vol. 2
26 May 2020
Here are 30 or so more ways to make your blog more entertaining to read and more pleasurable to write. See also: “A blogging style guide, vol 1”.
Choosing good words
- Don’t write “it was X and Y” when X and Y are pure synonyms. Prefer “it was a good outcome” over “it was a good and positive outcome”. This can make the single adjective that you do choose feel more exposed, but the concision is worth it.
- Don’t use intensifiers like very, extremely, or incredibly. Deleting these words can also make your writing feel more bare, but more considered.
- Don’t hedge unless you mean it. If you genuinely aren’t sure of something, say so. Otherwise just make your point; it’s OK if someone disagrees. For example, in a recent post I wrote:
“Everyone else is doing it” is not an excuse, but it is something of a mitigating factor.
I realized that “something of” was just fearful throat-clearing, so I deleted it:
“Everyone else is doing it” is not an excuse, but it is a mitigating factor.
This sentence is tighter and punchier. Enough improvements like this add up to appreciably better prose.
- Use a thesaurus, especially when you have another criteria you need your word to meet. For example, you might want a word that starts with a particular letter to help with alliteration, or one that sounds like another word to complete a pun. In a post about being a parent, I wanted to express the idea that I felt that I should write honestly because the result is compelling, but not too honestly because some of my readers are also my close relatives. I wanted a half-pun on “discretion is the better part of valor(/honesty)”. I looked up “honesty” in a thesaurus, and arrived at the pleasing “discretion is the better part of candor”.
- When using a thesaurus, don’t ignore the less precise matches further down the page. Sometimes these words can put a colorful curlicue on an otherwise mundane sentence. Don’t ever use words like “curlicue”, however.
- It is often said that you should write how you speak because this sounds clear and natural. This is good advice, but keep in mind that most people’s organic speech is meandering and confusing. When listening to my favorite podcasts I always notice how much worse the live shows are than those recorded in a studio. Don’t write how you talk; write how you would sound on a well-edited, multi-take podcast.
- Tell your reader where your piece is going and why. For example: “Much better than approach A is approach B. Let’s look at the reasons for this.” Or “In order to understand X, we first need to learn about Y.” I used to think that such functional phrases were artless and unnecessary. I switched from A to B and X to Y without warning and expected the reader to keep up. Then I re-read some pieces I had written a few months ago and was unable to even keep pace with myself. I decided that lucidity was more important than art and started writing more signposts.
Humour
- It’s possible and permissible to be a funny person - even a funny writer - but write posts that aren’t funny. Not every subject needs levity, and some subjects are incapable of supporting it. I used to be too determined to will whimsy where whimsy wasn’t welcome.
- That said, even when I’m writing a post that isn’t going to be funny, I still like to include a wry sentence or two in the introduction so that the reader knows that I’m human and on their side.
Technical writing
- Don’t make your toy examples too contrived; get as close to a real-life use case as you can. Don’t use a
FooBazzer when an EmailSender would work.
- Make it clear which parts of your examples should be copied and learned from, and which are arbitrary or even bad choices.
- Don’t use vocabulary that some of your audience might not know without acknowledging it. If the concept matters, explain it; if it doesn’t then summarize it in half a sentence and say that the details aren’t important today. If the concept really doesn’t matter then consider dropping the fancy word altogether. This ensures that your audience is never nervous about whether they are clever enough to keep reading.
Diagrams
- Diagrams are a lot of work and their text doesn’t get indexed by search engines, but they do make your explanations clearer. Create your diagrams using a tool that makes them easy to edit. I use Google Drawings but wish I used something better.
Process
I start writing a new post by spewing out notes, usually ideas and turns of phrase. I’ve probably already been thinking about the post for at least a few days, so I should already have a good backlog. When I run out of ideas I start shuffling around what I’ve got into an outline. I keep a section at the bottom of the page for ideas and phrases that I like but haven’t found a home for yet.
When I’ve got enough of an outline to start writing, I start with the introduction. I don’t actually write it, because introductions are difficult and not a fun way to ease into writing. But I do try to figure out roughly what it will say. What is the post about? What do I want the reader to think it’s about?
I often start writing for real with the section that seems like it will be the most fun. In posts about privacy violations, this is usually the part where I’m mean about the company that is stealing your data. In most other posts it’s whichever bit I’ve thought up the most jokes for. I start here in order to help me get excited about the post, and to help get the style of the post off on the right foot. Anything that starts a dirge will stay a dirge, but something that begins life with a sparkle has a chance of maintaining that sparkle throughout.
Once I’ve built up some speed I go back to the top, just after the introduction that still doesn’t exist, and start writing body paragraphs in rough order. My first draft is usually rushed, feels terrible, and exists primarily as a sentence-level outline. If there are any sentences or sections that feel too intimidating to write during this phase then I leave a TODO instead. Once I’ve finished the first draft I go back to the top, write the introduction, and start editing. Many sentences are awkward and don’t hang together, but it’s easier to polish them once I’ve got down the important information in a reasonable order.
When editing I start at the top, read the post, and make improvements as I go. Once I reach the bottom I go back to the top, read it again, and make more improvements. I stop once I get through a pass without making any improvements. Then I leave the post for a week - ideally longer - and repeat this process. Finally I send it out for feedback (see below).
Many successful bloggers do substantially less editing than me. I imagine that either my first drafts are worse than theirs, or my style is more ornamented and requires more work to be made intelligible.
Save your leftovers
When I’m finished, if I still have pleasing phrases without a home then I add them to my “leftover snippet” list. So far this list is over 1,500 items long. On review many snippets are not as good as I first thought, but I still often manage to recycle them into future writing or contextless Tweets.
Some of my favorite snippets include:
- She was putting it in terms that he could relate to, which he both hated and appreciated
- When the kids are exuberant and the adults are drunk and you’re neither
- I took refuge in a church where you could bring in outside food
- If you want the wisdom then you’ll have to wade through the exposition first
Post ideas
- Keep a list of writing by other people that you wish you had written
- When someone asks you a question, that’s a good excuse for a blog post
- Remember that everything you write is content marketing for everything else, which is itself content marketing for the thing that you really care about. If you don’t know what you really care about yet then that’s OK. A lot of people come to my site for the accessible cryptography explanations, stay for the series about parenthood, and email me to say that they feel professionally stuck and alone and to ask if I have any ideas.
- I’ve written a lot more about coming up with ideas for blog posts here.
Website design
- Don’t write your “About Me” page in the third person, since it was obviously written by you
- Do put dates on your posts. Some people will encourage you not to because your work should be timeless and immortal. But the world moves and most of your work won’t be. Knowing when a piece was written helps your readers to put it in context.
- Have a prominent “Best of” section so people who want to read more of your writing have a obvious place to start.
Asking for feedback from friends and family
- After someone reads your writing, ask them what they liked. This is more important than what they didn’t like because it tells you what to do more of. It doesn’t matter that no one liked my post “WeSeeYou: Democratizing De-Anonymization” (although I thought it was very good), but it’s invaluable to know that the central thesis behind “Programming Projects for Advanced Beginners” is spot on.
- If you don’t have a title yet, ask your reviewer for help. Titles are critical and difficult.
- Decide how much you’re actually willing to change the current piece based on feedback you receive. It’s reasonable to decide that you’ll correct spelling mistakes and re-order some paragraphs, but that you lack the appetite to rewrite the entire second half so as to bring out your secondary point. Feedback that would take too much work to address can still be taken as a lesson for the future.
Asking for feedback from strangers
I sometimes get unsolicited emails from kind strangers who have read my writing. I have several stock questions that I ask them:
- Which were your favorite posts? (I don’t ask them which posts they didn’t like, because that doesn’t matter much)
- What else would you like to read about?
- Who are your favorite online writers?
If the email is about my Programming Projects for Advanced Beginners series, I ask a few more questions:
- I don’t ask “how could I make the projects better” because that’s too vague a question and requires them to stick their neck out and tell me what I did wrong.
- Instead I ask whether they got stuck and frustrated anywhere, or whether there were details they wished I’d gone into. These are objective facts about their experience.
- I ask whether they’ve done all the projects in the series. If they haven’t then I politely ask why not. I’ve written 6 projects that are all quite similar, and if no one is doing all 6 then there’s arguably no point me writing 6 more like them. By asking this question I’ve learned that many people are looking for practice with the kinds of real-world technologies that will get them their first job. Writing Tic-Tac-Toe and Game of Life is fun, but they really want to learn how to use databases and HTTP and web apps. I’m therefore shifting my focus to this type of messier, real-world problem.
- Finally I ask “how is programming going?” This is an open-ended question that people can answer with as many or as few words as they like. Some people say “it’s going fine”, some pour their hearts out. Either way I learn more about my audience and hope they feel listened to.
If you found these ideas useful then it would be surprising if you didn’t enjoy Volume 1 too.
Here are 30 or so more ways to make your blog more entertaining to read and more pleasurable to write. See also: “A blogging style guide, vol 1”.
Choosing good words
- Don’t write “it was X and Y” when X and Y are pure synonyms. Prefer “it was a good outcome” over “it was a good and positive outcome”. This can make the single adjective that you do choose feel more exposed, but the concision is worth it.
- Don’t use intensifiers like very, extremely, or incredibly. Deleting these words can also make your writing feel more bare, but more considered.
- Don’t hedge unless you mean it. If you genuinely aren’t sure of something, say so. Otherwise just make your point; it’s OK if someone disagrees. For example, in a recent post I wrote:
“Everyone else is doing it” is not an excuse, but it is something of a mitigating factor.
I realized that “something of” was just fearful throat-clearing, so I deleted it:
“Everyone else is doing it” is not an excuse, but it is a mitigating factor.
This sentence is tighter and punchier. Enough improvements like this add up to appreciably better prose.
- Use a thesaurus, especially when you have another criteria you need your word to meet. For example, you might want a word that starts with a particular letter to help with alliteration, or one that sounds like another word to complete a pun. In a post about being a parent, I wanted to express the idea that I felt that I should write honestly because the result is compelling, but not too honestly because some of my readers are also my close relatives. I wanted a half-pun on “discretion is the better part of valor(/honesty)”. I looked up “honesty” in a thesaurus, and arrived at the pleasing “discretion is the better part of candor”.
- When using a thesaurus, don’t ignore the less precise matches further down the page. Sometimes these words can put a colorful curlicue on an otherwise mundane sentence. Don’t ever use words like “curlicue”, however.
- It is often said that you should write how you speak because this sounds clear and natural. This is good advice, but keep in mind that most people’s organic speech is meandering and confusing. When listening to my favorite podcasts I always notice how much worse the live shows are than those recorded in a studio. Don’t write how you talk; write how you would sound on a well-edited, multi-take podcast.
- Tell your reader where your piece is going and why. For example: “Much better than approach A is approach B. Let’s look at the reasons for this.” Or “In order to understand X, we first need to learn about Y.” I used to think that such functional phrases were artless and unnecessary. I switched from A to B and X to Y without warning and expected the reader to keep up. Then I re-read some pieces I had written a few months ago and was unable to even keep pace with myself. I decided that lucidity was more important than art and started writing more signposts.
Humour
- It’s possible and permissible to be a funny person - even a funny writer - but write posts that aren’t funny. Not every subject needs levity, and some subjects are incapable of supporting it. I used to be too determined to will whimsy where whimsy wasn’t welcome.
- That said, even when I’m writing a post that isn’t going to be funny, I still like to include a wry sentence or two in the introduction so that the reader knows that I’m human and on their side.
Technical writing
- Don’t make your toy examples too contrived; get as close to a real-life use case as you can. Don’t use a
FooBazzerwhen anEmailSenderwould work. - Make it clear which parts of your examples should be copied and learned from, and which are arbitrary or even bad choices.
- Don’t use vocabulary that some of your audience might not know without acknowledging it. If the concept matters, explain it; if it doesn’t then summarize it in half a sentence and say that the details aren’t important today. If the concept really doesn’t matter then consider dropping the fancy word altogether. This ensures that your audience is never nervous about whether they are clever enough to keep reading.
Diagrams
- Diagrams are a lot of work and their text doesn’t get indexed by search engines, but they do make your explanations clearer. Create your diagrams using a tool that makes them easy to edit. I use Google Drawings but wish I used something better.
Process
I start writing a new post by spewing out notes, usually ideas and turns of phrase. I’ve probably already been thinking about the post for at least a few days, so I should already have a good backlog. When I run out of ideas I start shuffling around what I’ve got into an outline. I keep a section at the bottom of the page for ideas and phrases that I like but haven’t found a home for yet.
When I’ve got enough of an outline to start writing, I start with the introduction. I don’t actually write it, because introductions are difficult and not a fun way to ease into writing. But I do try to figure out roughly what it will say. What is the post about? What do I want the reader to think it’s about?
I often start writing for real with the section that seems like it will be the most fun. In posts about privacy violations, this is usually the part where I’m mean about the company that is stealing your data. In most other posts it’s whichever bit I’ve thought up the most jokes for. I start here in order to help me get excited about the post, and to help get the style of the post off on the right foot. Anything that starts a dirge will stay a dirge, but something that begins life with a sparkle has a chance of maintaining that sparkle throughout.
Once I’ve built up some speed I go back to the top, just after the introduction that still doesn’t exist, and start writing body paragraphs in rough order. My first draft is usually rushed, feels terrible, and exists primarily as a sentence-level outline. If there are any sentences or sections that feel too intimidating to write during this phase then I leave a TODO instead. Once I’ve finished the first draft I go back to the top, write the introduction, and start editing. Many sentences are awkward and don’t hang together, but it’s easier to polish them once I’ve got down the important information in a reasonable order.
When editing I start at the top, read the post, and make improvements as I go. Once I reach the bottom I go back to the top, read it again, and make more improvements. I stop once I get through a pass without making any improvements. Then I leave the post for a week - ideally longer - and repeat this process. Finally I send it out for feedback (see below).
Many successful bloggers do substantially less editing than me. I imagine that either my first drafts are worse than theirs, or my style is more ornamented and requires more work to be made intelligible.
Save your leftovers
When I’m finished, if I still have pleasing phrases without a home then I add them to my “leftover snippet” list. So far this list is over 1,500 items long. On review many snippets are not as good as I first thought, but I still often manage to recycle them into future writing or contextless Tweets.
Some of my favorite snippets include:
- She was putting it in terms that he could relate to, which he both hated and appreciated
- When the kids are exuberant and the adults are drunk and you’re neither
- I took refuge in a church where you could bring in outside food
- If you want the wisdom then you’ll have to wade through the exposition first
Post ideas
- Keep a list of writing by other people that you wish you had written
- When someone asks you a question, that’s a good excuse for a blog post
- Remember that everything you write is content marketing for everything else, which is itself content marketing for the thing that you really care about. If you don’t know what you really care about yet then that’s OK. A lot of people come to my site for the accessible cryptography explanations, stay for the series about parenthood, and email me to say that they feel professionally stuck and alone and to ask if I have any ideas.
- I’ve written a lot more about coming up with ideas for blog posts here.
Website design
- Don’t write your “About Me” page in the third person, since it was obviously written by you
- Do put dates on your posts. Some people will encourage you not to because your work should be timeless and immortal. But the world moves and most of your work won’t be. Knowing when a piece was written helps your readers to put it in context.
- Have a prominent “Best of” section so people who want to read more of your writing have a obvious place to start.
Asking for feedback from friends and family
- After someone reads your writing, ask them what they liked. This is more important than what they didn’t like because it tells you what to do more of. It doesn’t matter that no one liked my post “WeSeeYou: Democratizing De-Anonymization” (although I thought it was very good), but it’s invaluable to know that the central thesis behind “Programming Projects for Advanced Beginners” is spot on.
- If you don’t have a title yet, ask your reviewer for help. Titles are critical and difficult.
- Decide how much you’re actually willing to change the current piece based on feedback you receive. It’s reasonable to decide that you’ll correct spelling mistakes and re-order some paragraphs, but that you lack the appetite to rewrite the entire second half so as to bring out your secondary point. Feedback that would take too much work to address can still be taken as a lesson for the future.
Asking for feedback from strangers
I sometimes get unsolicited emails from kind strangers who have read my writing. I have several stock questions that I ask them:
- Which were your favorite posts? (I don’t ask them which posts they didn’t like, because that doesn’t matter much)
- What else would you like to read about?
- Who are your favorite online writers?
If the email is about my Programming Projects for Advanced Beginners series, I ask a few more questions:
- I don’t ask “how could I make the projects better” because that’s too vague a question and requires them to stick their neck out and tell me what I did wrong.
- Instead I ask whether they got stuck and frustrated anywhere, or whether there were details they wished I’d gone into. These are objective facts about their experience.
- I ask whether they’ve done all the projects in the series. If they haven’t then I politely ask why not. I’ve written 6 projects that are all quite similar, and if no one is doing all 6 then there’s arguably no point me writing 6 more like them. By asking this question I’ve learned that many people are looking for practice with the kinds of real-world technologies that will get them their first job. Writing Tic-Tac-Toe and Game of Life is fun, but they really want to learn how to use databases and HTTP and web apps. I’m therefore shifting my focus to this type of messier, real-world problem.
- Finally I ask “how is programming going?” This is an open-ended question that people can answer with as many or as few words as they like. Some people say “it’s going fine”, some pour their hearts out. Either way I learn more about my audience and hope they feel listened to.
If you found these ideas useful then it would be surprising if you didn’t enjoy Volume 1 too.