A blogging style guide | Hacker News Reader

A blogging style guide

robertheaton.com

495 pointsmbaytas188 comments

> 29. Be sparing with pronouns in technical writing. It's better to repeat a noun than have it be unclear what "it" refers to.

This is the most valuable piece of advice I hope most readers will take from this article for their technical writing.

This advice ("avoid unspecified pronouns") also applies to communicating in text, period. SMS, IRC, Slack, in all of them you can avoid a lot of confusion by being clear in your nouns.

BAD: "We're hooking up the refresh token to the API next week. It was broken by a bad commit, but that is fixed" GOOD: "We're hooking up the refresh token to the API next week. The token was broken by a bad commit, but that commit is fixed"

This advice is one of the two most important tips for clear communication in text I know of. The other tip is: don't ask an A or !A question - you'll just get "yes" or "no" as an answer. Instead, ask to confirm A and not B.

BAD: "Are we releasing this week? Or next week?" GOOD: "We are releasing this week, not next week, right?"

This second tip, however, requires a lot more work to make natural.

Great examples. For the release, I would specify the date, time and timezone.

The A or !A thing never fails. But it's more a hack to work around other people having poor communication skills. It's also good advice to pay attention to the question being asked of you, and actually answer it. So if someone asks you, "Are we releasing this week? Or was it next week?", don't reflexively answer "yes" or "no".

Non native English speaker writing: I have perfect understanding of the language and I can even differentiate between different accents, but one of things I struggle with the most is written communication. I don't seem to be able to express my thoughts as fluidly as I can orally. My brain just freezes out whenever I try to write "complicated" sentences which I find extremely irritating. I don't know why this is and would love some pointers on how to improve my (and others in the same boat) writing skills.

Read a lot of books of various style and content. Meanwhile, practice writting in a rewarding and safe environment. That's it.

> My brain just freezes out whenever I try to write "complicated" sentences which I find extremely irritating.

Don't do this. Follow "The Economist Style Guide" instead:

"Clarity of writing usually follows clarity of thought. So think what you want to say, then say it as simply as possible."

I like the version of a former judge on Germany’s Supreme Court: “Think like a philosopher, write like a peasant”.

If only German philosophers had taken that advice.

A guest lecturer from Germany comes to a university classroom and begins giving his speech in German. After five minutes, a bored student gets up to leave.

"No, wait!" interjects the German lecturer. "I've almost gotten to the verb!"

In tsarist Russia, authors were paid by the page, which is why Dostoevsky's stories are so verbose and indirect. I don't know what's Nietzsche's excuse.

Or German peasants!

There are some writers that seem to produce work that is just incompatible with my brain.

A recent example for me is Sam Harris' book Waking Up. It feels like somebody could take that book, remove some ornamentation, and state the ideas more plainly. It isn't a difficult text, but I find myself having to reread pages to clear the fog more than I normally do.

This is very good advice. I think my problem is I try to sound more "intelligent" and well-spoken. Maybe that's because English isn't my first language. In any case, the most annoying thing for me is to not be able to tap into my inner thesaurus. When I read other people's articles, comments and book I often find myself thinking "why did I not use that turn of phrase in my previous blog post".

I can sympathize with you, as I shared the same woes. Don't torture yourself though. Quite often the ornamental form simply hides the lack of intellectual depth in the content. Free yourself from such thoughts and the rest will follow.

I really recommend "The Economist Style Guide". Please read through it, then read again to see how it was applied to itself (!). Then write a short passage, and revise it to adhere to the recommendations -- don't be surprised if this will need several passes though!

You will be surprised how much this can improve your writing, but also structure your own thoughts.

Trying to sound intelligent can actually have the opposite effect. I like the quote "If you can't explain something simply then you don't understand it well enough."

As for picking up idioms, I think it's something that happens gradually as you are exposed to more writing by native speakers.

Very good advice, I'll save that quote.

Also, if you’re struggling with how to phrase something, try omitting it instead.

I think there's a difference between lean prose and choppy prose. [1]

Lean prose (Hemingway) is elegant simplicity.

Choppy prose (most amateur writers) is tiring and jarring.

Despite their seemingly shared characteristic of simplicity, it takes a lot of practice to achieve the former.

[1] https://www.helpingwritersbecomeauthors.com/common-writing-m...

In my freshman creative writing class at university, my professor recommended using stream of thought and it seemed to work very well.

Just literally start writing everything you think, as you think it, everything, just write it. Don’t fret over spelling or even bother with punctuation, no matter how disjointed, just stream and eventually you begin to somehow fall into focus and the words will flow much much better.

Once you’re finished and have gotten your point across, just go back and edit.

We all kinda looked at each other and rolled our eyes because it sounds so strange, but it really does seem to work.

For those interested in learning more about this method, Peter Elbow is the relevant author. His books Writng without Teacher and Writing with Power go into more details.

> Writng without Teacher

Feel like you might have taken the "don't fret over spelling" part of the method a bit too literally here.

I have to admit I am a little bit disappointed that its not the actual title of the book

Yeah. I blame it on fat fingering on a phone.

For reference, it’s actualy Writing without Teachers.

Thanks for letting me know.

This is good advice, because it also forces you to learn to edit what you've written. What I've seen is that editing is a separate skill from writing that needs some effort to learn.

Maybe editing is not that important for blog posts. Shorter texts can sometimes be written in one pass, but for producing anything longer it's a vital skill.

+1 for this. I know it works for me, but I still get stuck sometimes trying to get the sentence perfect the first time. But this only slows me down. Once I have something, it is relatively easier to edit it into a good sentence than it is to find a good sentence from the beginning.

I think it is the same way when I write code. First get something to work, then refactor it works really well.

PG's essay on writing says this too, this helps a lot

I (and a lot of others) call this "word vomit", and it's definitely very helpful.

I do something similar with code, "code vomit" (how creative). Do whatever it takes to get the damn thing working, then go back over it and apply as many good coding principles as you can.

I think the more crude advice of "write drunk, edit sober" comes from a similar line of reasoning; alcohol is the push to start the stream of consciousness.

Funny, I'm the other way around.

Anyway, what I do if I sort-of know what I want to write: open a word process or anything, set it to a bullet list, then start to write. The bullets can be really short or somewhat longer if I happen to think of a nice way to write something down, but by being bullets, it's clear that it's not the final form, and that I can "cheat" and just write down a few keywords as long as it's clear to me what I want to write.

This allows be to easily move things around, and write about as quickly as I think, and thus end up with a bullet list with proper structure for what I want to write. I can then relatively easily convert that to a proper story.

(That's not how I wrote this comment, so it's bound to feel somewhat more chaotic/stream-of-consciousnessy.)

One thing that might help (and certainly won't hurt): read more.

If you read properly written English (I'd exclude from this much of the web and academic writing), you'll start absorbing the patterns.

Are you immersed in the English speaking world everyday ? At work, at home, etc. ? Then it'd make sense things come easier to you verbally. I also believe we express less complex thoughts in oral communication compared to written sentences. Because we are obliged to keep it simple to keep the flow going. YMMV though.

1) is to get over the need for complicated sentences to express complicated ideas. you don't need big words or convoluted sentences to "sound intelligent", even if you have a vast vocabulary. "write like ernest hemingway" is the best writing advice i have ever been given.

2) just write more, it's a practiced skill. being able to understand different "dialects" of english is actually a superpower you can use to your advantage as a non-native speaker. publish whatever you write. solicit feedback. you'll always write better than 10 essays ago.

Not that it may mean much to you, but your writing here is far better than many native English speakers I know. You writing is better than many US-born people I went to university with.

Unless you are writing something literary, why do you want to write complicated sentences? writing is just a means to communicate if you deprive a section of your readers(say non native english speakers) your writing failed!

For the problem of struggling to write but fine with oral communication my suggestion is to just record your thoughts orally on your phone/laptop transcribe them using google docs and than your job would be reduced to editing rather than writing from the scratch which looks easier to me but i can be wrong.

There is nothing wrong with adopting a more conversational style for professional writing, particularly in our industry. If you were in e.g. academia, failure to adopt the consensus tone of journal articles might be career-limiting, but you can get a way with an awful lot in tech.

Your comment seems comprehensible; I wouldn't have been surprised to see it from a native speaker in an internal email thread.

My biggest concrete suggestion is to write 10X more in 2019 than you did in 2018, and explicitly ask people for feedback on it. (10X is a pretty big leap, but most people write far, far less than they think they do, and the cure for being inexperienced is experience.)

Did you ever try to use speech-to-text-software? I have written dictandu for that: https://www.dictandu.com/

You can just dictate like you would talk and averwards use the style and spelling assistant to improve what you dictated.

I use speech to text for Chinese a lot. Or a smartphone keyboard. Or I write on paper, scan it and send it to someone to type it out and edit it. Cool that you work on things like that, I’ll check it out when I get home!

I highly recommended reading some Hemingway. He has a very beautiful writing style. It's a masterclass in efficiency.

I have to write academic work in a rigid format, but I try to mimic much of his style in my other writing (reflective pieces, opinion pieces, formal communications at work...).

There's also an app/webpage called the Hemingway editor I would recommend.

If it could help, maybe you are talking about http://www.hemingwayapp.com/

Yes, that's the one. I didn't have a bookmark for it on my phone. Thank you for linking to it.

Is it any easier if you write first in your native language, then translate?

This is typically a very bad way to write a good text, as you will use idioms that simply are inefficient to use in the target language. If I would write a text in Swedish and then translate it to English, my workload would likely more than double.

The old adage "write drunk, edit sober" applies here. The real point is to stop censoring. Writing is really two skills:

- Building the habit - Being comfortable editing out things that don't work

BTW, the your original post came across clearly and was solidly written. Your prose will come with practice :)

Get to it! :D

Edit: Hilariously, this is also on the front page now, https://goinswriter.com/write-drunk/ but they are being disingenuous in their interpretation.

I'll echo others that this post reads well, better than many native speakers I work with.

Beyond that, my advice to almost all writers is to read your work out loud.

Better yet, have your computer read it to you.

You can only improve it by practicing it. You will get better over time as long as you keep on practicing.

>I don't know why this is and would love some pointers on how to improve my (and others in the same boat) writing skills.

Read a lot of different kinds of writing and keep on writing yourself. Eventually you'll develop better skills.

If you mostly write on a particular subject, read how others express things in that domain.

Try to describe something complicated and then compare it to how people regarded as great communicators approached the same subject.

Choppy sentences are a common problem in writing, and there are prescribed ways of dealing with them. [1][2]

[1] https://www.usu.edu/markdamen/WritingGuide/05choppy.htm

[2] https://writing.stackexchange.com/questions/10875/what-can-i...

(Also non-native English speaker) I feel the same way. I think that when I speak, my listener gives me cues (e.g., nodding or frowning) and I react to them: I reformulate if they seem confused or I keep going if they look satisfied. When I write, I don't have that immediate feedback, and I typically write more than is necessary. My writing suffers because it takes too long to convey ideas that are not confusing, but that I fear may be. The old adage "keep it simple, stupid" applies also to writing, and it's really hard.

By the way, I thought that this paragraph that you wrote was perfect, very easy to understand. If you write like this all the time, then don't worry: people will understand you.

In the statement of the problem, I detect no trace of the problem, therefore I offer no solutions. The length and complexity of each of these four sentences is within the window of what I consider tasteful. One could write sentences more complex, or infinitely complex, but that's mostly to be avoided, in my opinion. Complex sentences, unless written with great care and subtlety, tend to call attention to themselves and to the writer, and that's a failure. If I'm distracted thinking about how the writer is showing off, I'm no longer thinking about what I'm reading.

Meanwhile, strategically sprinkling in the occasional short simple sentence is a fine way to achieve various desired effects, including variety of cadence. And of course there have been famous and successful writers of English who have gone farther than that, to the point of choppiness - most notably Ernest Hemingway. "I had no feeling for him. He did not seem to have anything to do with me. I felt no feeling of fatherhood." To me that also starts to draw attention to itself, but at least he can't be accused of being bombastic or grandiose.

Interesting. That's backwards for me. I usually wish I could go back in time and reformat what I'm saying multiple times as easy as I can move a text cursor. I also wish people wouldn't get impatient with me while I blabber nonsense until I can get my thoughts in order and spew out a few concise/complicated sentences that I'll need to repeat a few times with hand gestures for them to understand what I'm saying. I wish they could also go back in time and rehear what I said however many times they need. Heck, that goes for me, too. I wish I didn't need to ask people to repeat what they said so many times.

I wonder if you would find it helpful to write in an app like http://hemingwayapp.com or Grammarly.

I love that the second point is basically:

"No, what you write won't matter, but nothing else does either, so go ahead and write."

Curiously, that makes me want to write more.

It's going all the way through to the other side, in the spirit of Camus. The world is so saturated with absurdity that absurdity is the only place to grab hold.

> The world is so saturated with absurdity that absurdity is the only place to grab hold.

That's why my blog is called something like "World's Absurd States" which sounds better in Turkish. But also I think nothing I write matters so I keep writing. I write about so many different subjects that people read the article they came for and they leave without checking other stuff. It's true that you have to find a nich and write only about that subject. I don't even think people have patience to read my long articles. But I write for myself.

My most popular post by far is a brief article about the relationship of nipples with litter size. Is there a relationship with nipple number and average litter size? I still cannot understand why so many people are curious about this topic. Everyday a few people drop by to read that article. Unfortunately, in wordpress.com I cannot see which search terms leads to my article.

Google analytics is really easy to set up, and would allow you to see what lead to your page. That would mean you have a google tracker on your site though.

I read that GA is only available if I upgrade to Business plan which is obviously out of the question for me now.

Do a thing for yourself, not others, and most of the reasons not to do the thing seem to fade away. If I truly want to write another Scheme interpreter for fun I just do it now, instead of thinking "several thousand people have already done this, it's useless to do again."

There's only so much a person would do for themselves though. I'd like to think most people eventually would want to work on something that has an impact on at least one other person. I would say having a balance of projects for oneself and projects that provide utility to other would be optimal.

Indeed! CirclMastr (someone who leveled up to 99 in the very first portion of Final Fantasy VII over the course of 500 hours) puts it even better:

> It is because nothing has meaning unto itself that we are free to create meaning, to make metaphor, and in doing so reflect on ourselves and our world.

Source: https://www.theverge.com/tldr/2017/4/11/15255852/final-fanta...

Well timed – I’ve been trying to get back into blogging, as a way of sharing and giving back, as well as improving my personal ‘brand’.

I was never really happy with the visual format of my site, which I think put me off writing at times - “if it were me, I’m not sure I’d read this in this format, it’s too visually taxing”. However with a quick style change to something much more basic, I’m feeling much more confident.

I think my final hurdle, which this article may help with, is my writing style. I get the impression that my ‘style’ changes fairly regularly, or depending on the topic or post I write for a different audience. This likely doesn’t matter too much for those visitors who come for a single post and move on, but anyone who would like to peruse around may get a slightly jarring experience.

You've basically summed up my experience: I just revamped my blog and pushed myself to put some content out, and now I'm much more receptive to putting stuff on it. Writing well is still difficult, though…

This is a similar issue to my own one; I'm way too easy to distract with the promise of neat tech or extra features, so end up spending longer coding the site than actually writing anything on it.

Wonder how many other developers end up falling into that trap?

I did, and realized that I'd spent all this time that was meant to be for writing on coding / finding cool tools / setting things up. Guilt overpowered the fun in this and I threw it all away and just installed Wordpress. I still play with the tech, but in a different time block, away from the writing itself.

So I used to have a blog, but I felt this pressure to publish stuff regularly. And that showed in the quality of posts I wrote; shitty, unsolicited articles about nothing. And when I didn't have enough content (whatever that means), I just filled it with random garbage. I've deleted that blog entirely since then.

I've also come to the conclusion that there are two kinds of posts - regular, essay-like blog posts and just random thoughts. These random thoughts could just be 1-2 lines or just a paragraph. You don't need to develop them into a full article. Twitter is designed for this, but Twitter is also suitable for a lot of other things, so you shouldn't feel like you can't have these in your blog.

Maybe I should write a blog post about this lol. I've been collecting topics to write in a text file so that I won't run out of stuff to write. But I now think it's perfectly fine to go 3-4 months without an article, until you feel like writing one that's worthy. I know this is a bit contradictory to point 2/39 in this post, but I just thought I should share.

I remember when you could just throw just anything you'd like up on a site and call it good. Curating was (or could be) part of it, but if you wanted to say, "fuck curation" you could. It was YOUR website; it's not a curated exhibit in a museum. Just be an amateur at something. Make a lot of noise!

I think that's ok if you're writing for yourself or for a bunch of friends.

But good blogs with steady readership generally curate. Readers gravitate towards quality (because time and attention span are precious) and lose interest fast if the quality is all over the place.

Most bloggers write more posts than they actually publish. The published ones are the ones that pass muster. We don't see the stuff in their drafts folder.

> I've also come to the conclusion that there are two kinds of posts

I had come to this same conclusion for my own posting habits! I'm hoping to finish my website this weekend and will probably implement a microblog for the little thoughts and a (macro?)blog for the bigger pieces.

(I'd just use Twitter as my microblog but I like the idea of inline hyperlinks in my posts more than is perhaps healthy.)

A lot of comments on HN could probably be turned into blog posts by their authors.

I think that's what my blog will be: elaborations on comments I have about HN articles.

> I've also come to the conclusion that there are two kinds of posts - regular, essay-like blog posts and just random thoughts.

Blog posts are not limited to those two kinds. I have a blog where I don't write too often. Whenever I have a programming problem whose solution couldn't be found easily by searching on internet, I write a small technical and to-the-point post about it, hoping that it will be useful to anybody else that may have the same issue.

If you feel pressured to publish stuff regularly, probably you're keeping a blog for the "wrong" reasons.

Slighty off-topic but I find (as a non-native English speaker) the whole deal with ”he/she” to be super annoying when reading. Especially when the gender is basically not important such as when talking about what the dentist said (or w/e). Is there any trick so to speak to avoid such situations?

Also, in Swedish we have ”he/she/* = han/hon/hen”. Which is soo useful and I am still kind of amazed that the term ”hen” is a relative modern invention. I wonder how in earlier days people referred to other people when the gender was not the main focus. Maybe it was always more important before? Or was perhaps the use of titles (the Dentristess..?) a way to denote gender an important communication tool?

They

https://en.wikipedia.org/wiki/Singular_they

See point 19: >"They" is a great word for referring to an unspecified person of an unspecified gender.

I guess in earlier days they used the form they found appropriate and didnt think about it much more. Also, as much as you and I like it, the gender-neutral pronoun in swedish is relatively modern enough for it to be yet hardly used in everyday communication (YMMV of course).

I heard at some point (maybe in school, maybe not) that if the gender is not known, you just pick one and stick with it. Some people also take the approach of switching back and forth out of fairness. I find this even worse than saying "he/she".

Historically in English, the masculine form was the default gender-neutral term.

"Mankind" to refer to all humans.

"All men are created equal" to refer to all humans.

"No one shall be arbitrarily deprived of his nationality nor denied the right to change his nationality" refers to all humans.

More recently as other comments have pointed out, singular "they/their" has become more accepted. "No one shall be arbitrarily deprived of their nationality nor denied the right to change their nationality".

> Historically in English, the masculine form was the default gender-neutral term.

Actually, singular "they" predates generic "he" by several centuries. Generic "he" was an 18th-19th century invention.

https://en.wikipedia.org/wiki/Singular_they

Just use the generic he[1]. It's classic and has the benefit of not injecting politics into an unrelated issue.

[1]: https://en.wikipedia.org/wiki/Third-person_pronoun#Generic_h...

So the problem is that there’s no way to disguish the “generic” he from the “gendered” he, and it is very easy to read everything that uses the generic as being gendered, and then you suddenly have a world where only guys exist, which is probably some sort of political statement.

The singular they[1] has precedent going back to the fourteenth century. Just use that.

[1]: https://en.m.wikipedia.org/wiki/Singular_they

> and then you suddenly have a world where only guys exist, which is probably some sort of political statement.

I wish people who felt about that strongly and wanted to make a political statement just used the gendered she creating the fictional world where only girls exist. That would have been so much simpler and avoided so much pointless arguments over the grammatical number and gender of pronouns.

As a mathematician I use the generic she as it's got a better expected value if you're optimizing for being right.

I just use "they," "them," "their." Not sure why this isn't more common.

> 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.

Radically disagree with this. Starting everything from recipes to teardowns with a story about your first dog is getting to be a real curse of the internet lately.

Agreed. If you’re trying that hard to build a relatable hook, maybe what you’re writing about just simply isn’t that important/useful?

If it's too artificial, that's right. But, answering the question "why am I blogging about that? Why is that important?" is a great way to start an article. And, most of the time, you can do it with a story-like setup.

I think doing so is a major mistake. The reader found the text through either searching or reference (like a link on HN), and thus the answer "why am I reading this" is already provided before they even loaded the site. It is much better to hook the reader with what makes the text unique, confirming the decision to continue reading, and then further down explain why this is important, the history, and why the author is writing about it.

Indeed, but IMO that's the role of the "chapô" (not sure about the English word there; abstract? leading paragraph? I mean the short first paragraph, sometimes written in a different font, that's here to engage the reader). So, in an article titled "is blogging still relevant?", that first paragraph could be something like

"Contrary to popular belief, blogging is still a viable economic activity nowadays. Finding readers may be harder than before, and require some more efforts from the reader, though".

And, then, have your article start as a pure story :

"You're in front of your computer, facing the blank screen. Finding ideas is hard, today. You start asking yourself "Does it even make sense? Bah, nobody will read my prose anyway". Then, you close your word processor and look for the new cat video, thinking it's a better use of your time. Well, you couldn't be more wrong. Blah blah..."

OR, after the leading paragraph, you could still use a narrative stucture (setup, problem, attempts to solve the problem), but in a low profile version, ie without the made up character:

"Numbers don't lie: there are 10 times more blogs nowadays than 5 years ago, and people spend 5 times less time on blogs, since they spend most of their online time on facebook or instagram. One might wonder if starting a new blog today still makes sense. Well, first, blah blah..."

I guess it's a matter of preference. I often dislike this approach in talks on technical conferences, where the current trend seems to be to spin everything into a personal story, even when it's clearly forced. I don't mind reading a blog where there technical part is wrapped into "I had this real-life problem and it boiled down to solving this software bug ..." kind of a story.

I think the "quickly" in your quote is the crux for me. I'm quite happy to read a paragraph or so of anecdata that provides a useful or motivating analogy/story.

OTOH, if your article is 3k words, I'll be gone if your 'relatable hook' appears to be a third of the article. Weave it in, be didactic!

The recipe thing is 100% driven by SEO, and yes, it's annoying, even to most of the people who are forced to do it if they want their recipes to rank.

Beyond that, I don't see an increasing trend of this on the internet or elsewhere, nor do I think it's a mistake or even unpopular. Features have been written this way for a very long time, vs the "inverted pyramid" style of news articles. Done well, it's a great format, even if the grumpy HN crowd typically finds it too meandering and relational and anecdotal and would (allegedly) prefer a bullet point list of the facts :)

I think the key difference is the audience. For a lot of food bloggers that share their recipes, the initial group of readers is loyal fans. They want to hear the stories and the recipe is almost secondary.

When you find a recipe through search, you want the recipe and have to wade through the story and the photos to get to it and that's frustrating. Oddly enough, it's also what may help that article rank higher in search too.

You'd like my website.

I did my entire 'human framing' in a single paragraph on a single "Its January 2017, next steps" article.

It was my worst performing article, now I only release studies.

I agree about avoiding those long, terrible, narratives that introduce something completely unrelated, but I don't think he's suggesting that. Framing can simply be one opening sentence that states the real life human problem you're solving (the "why" they should read it that he's talking about). That should be following by the lede -- which is the solution to the problem you just mentioned. The rest of the writing is your proof of the solution.

It's a pretty simple formula that works. I've been doing it since 2009 and my blog has won copy writing awards and a webby award.

I had to think about why this bothers me so much. I read HN a lot and there's a wide range of quality. So even though I actually like human framing conceptually, having to wade through it before figuring out if the article is worth reading in the first place is bothersome.

I read both types. Sometimes I want the short and to-the-point version and sometimes I want the long form with a story. I think there's a place for both. Write in the way that makes sense for your personality.

Definitely agree.

Writing on the Internet, especially informative writing, needs to be crystal clear and clean.

Do people write (blog) for themselves any more? This blog post frames the whole experience as an extroverted attempt to please the audience that is not yourself. Which is totally fine if you regard blogs as a medium directed primarily outwards, at others. I am just curious whether anyone writes primarily for themselves (in order to better organise their thoughts, or leave a reference for their future self), where any readership is purely accidental, not the raison d'etre? I know that I do.

I plan on doing something like that. I work as a programmer and recently I've been tackling some interesting problems and I've been thinking about documenting everything (the problem, my approach, my solution etc...) my goal is to have that blog as a future reference for myself and track my progress... if anyone comes to my blog and read that stuff then that is even better!

Sure we do. I personally I have a programming blog mainly as a "reminder" about how I solved the programming problems I had. And it happened to me a few times that searching for a solution led me to my post :)

Yes, people do! From my time in HN, I've accumulated a list of links to smaller/niche blogs, that you wouldn't stumble on by chance, except if you were searching for something extremely specific. You don't have to add analytics and play the numbers game, but just as ig0r0 mentioned, it's a great exercise to improving your writing, document your learning experience or an obscure solution for easy future reference.

It's easier than ever to get started (as easy as forking a Github project and uploading your markdown), and as a bonus it might also look good on a CV.

Many of the reasons why I blog are for my own benefit, but it is also fun if people read what I write, so it is a mix really. My reasons in roughly order of importance:

- Knowing what I think

- Sharing knowledge

- Venting

- To learn (when I get comments on my views)

- To remember better, e.g. for books I've read

- To have an archive to refer people to

- For the thrill of having people read what I write

- For self promotion

I wrote about it in more detail here: https://henrikwarne.com/2017/11/26/6-years-of-thoughts-on-pr...

> - Venting

> - For self promotion

I use my blog for venting as well. And love the experience, knowing that it's not a social network and no-one will rush at me screaming angrily. I just worry sometimes that some of my rants go against the dogmas of the mainstream liberal orthodoxy, and if someone did chance upon my blog, they might get upset — and oh, I don't know, fire/not hire me.

I write for myself. To repeat an aphorism, I don’t write because I can write, I write because I can’t not write.

I couldn’t even begin to confidently tell anyone to read what I write. Statistically, 90% of my blog posts sink without a trace. My last post was about a novel but highly pessimum solution to a programming puzzle.

Who ought to read that? And why? It was a pleasant diversion to write, and if someone finds it a pleasant diversion to read, great! But how could I tell anyone that they ought to read it?

As it happens, I have been blogging for fourteen years, and if you throw enough spaghetti at the wall, some of it sticks. Thus, I have a small but durable reputation as an author.

In that time, I have resisted the urge to closely track metrics and adjust my writing to improve its popularity. I’ve tried to get better at being me, without becoming a copy of any of the bloggers that are really popular.

It’s my hobby, it’s supposed to be for me and for those who have their own reasons in finding it delightful.

...All that being said, within the non-negotiable bounds of writing for myself, and speaking in my own authentic voice, there is lots of room to improve my writing.

Structuring a post to be easier to digest isn’t just about writing for others, it is also a forcing function for structuring my own thoughts. In what order should I present this idea? What is essential, what is inessential, and what actually detracts from the essential idea?

Questions like these work their way back to improving my own thinking about an idea, and that is part of why I write and what I gain from it. This is why I unapologetically revise my posts dozens of times when they hit HN or go viral on Twitter: The feedback offers a clue as to how well I’ve structured my thinking, and restructuring it helps me understand the subject better.

Writing is rewriting. Without agreeing or disagreeing with any specific piece of advice in TFA, the general idea of applying some structure to writing to make it digestible nad to communicate your ideas clearly is valuable not just for the writing itself, but for your own thinking.

If time allows it and I want to ensure I understand some concept, explaining it to someone tend to be very useful. Writing a blog post is then a great way to do so without requiring one of my friends to listen!

I do this without even publishing the posts. As mentioned in one of the other comments, I am vary of making these accessible for the public due to lack of "oversight". I feel like there's a responsibility when sharing information, and if I'm not 100% sure what I've written is correct, I don't want to mislead people. And even if correct, one should really ask themselves if it actually adds something to the topic which is otherwise not easily accessible. I think this is especially important to ask today when there is so much information already available.

Hence I actually think writing blog posts as means of understanding is a really goof approach; whether or not the piece should be made public is something that should then be judged case-by-case.

“Rubber-duck writing.” I like it.

vary -> wary

goof -> good

Cheers :) Autocorrect got me real goof!

I do. I'm honestly not sure what my reasons are, I certainly don't have any kind of "following".

Mostly I think I get an enjoyable sense of accomplishment from getting down "properly" the stuff I find myself contemplating and discussing with people. It's almost like flushing a write buffer: get it from working-memory to blog, and it's done!

There's definitely a learning process and I feel I'm noticing improvements to my output and approach, which is also a satsifying outcome.

Link -> https://mcconnellsoftware.github.io/

I'm a few years and 200+ posts deep on my blog and I still mostly write for myself.

Not because I'm a selfish dickwad, but most of my posts ends up being drawn from real world development experience, and to further improve my ability as a developer, I write about the experience openly.

It seems like a win win situation. I get a better understanding of what I'm doing and it becomes a searchable reference for myself and anyone else who happens to stumble on one of my posts.

I think a lot of bloggers write primarily for themselves. But I also think many are secretly or subconsciously hoping it'll find some kind of audience. Which makes sense, because if you literally do not care at all whether anyone else reads this or finds it useful, you wouldn't bother publishing it.

A blog is a communication device, so it doesn't make a lot of sense to do it solely for yourself. I think to myself a lot (sometimes out loud) and I write for myself a lot, but I wouldn't talk into a phone with a dial tone to myself :)

So perhaps this piece is also useful for people who write primarily for themselves, but also would like to remove any barriers to others finding and enjoying the fruits of their efforts.

> if you literally do not care at all whether anyone else reads this or finds it useful, you wouldn't bother publishing it

Remember the diaries (I wonder when they gained popularity? in the 18th century? in the 19th? surely they've been with us longer than that). They could be read by others, and indeed there was a tradition for young lovers to give each other their diaries to read, but they were (or were supposed to be) written primarily for those who wrote them.

Same for laboratory logs (or other professional logs; I am not sure who kept them besides sea captains). They could be read by others, and might be informative to others, but were written primarily for the writer himself.

As for publishing, web publishing is so easy and makes the writing so accessible it's arguably easier to "publish" your writings on your web site than to keep them in a notebook in a drawer.

But those are two different forms of writing: keyboard vs longhand. It’s not easier to blog than write to a local text file.

> It’s not easier to blog than write to a local text file.

For many developers who have harnessed static site generators that turn local markdown (or orgmode, etc.) files into htmls, it is essentially one and the same thing.

Does blogging to keep from repeating yourself count as for yourself or for others? That's why I've kept a blog since 2000 or so. I'm no extrovert, but I still have to deal with people and I often end up making the same observation or explaining the same thing over and over in different conversations. When I catch myself doing that, I try to frame that thought in the clearest way I can as a blog post. Then I can point people to it in chat/email, or people I don't even know can find it themselves. In some ways it reduces the amount of direct interaction I have to be involved in.

Oh right! I completely forgot about that reason to blog :-) I think before your comment I've at least one developer who started doing just that.

"For yourself" and "for an audience" are not mutually exclusive. I find them to be mutually reinforcing.

Fo myself, as the topic and exposition are intrinsically motivated. For others, as that goads me to bidging chasms and leaps of reason otherwise obscured, and for which Future Me often thanks Past Me.

I write for myself first but it's a great feeling when others find value in my writing. As such, readers are usually on my mind. My posts often evolve over time.

This is great, although I'd suggest people steer clear of Strunk and White -- it's ancient and full of nonsense.

Instead, try Steven Pinker's "The Sense of Style", "Artful Sentences" by Virginia Tuft, and a new favorite, "First Write a Sentence" by Joe Moran.

> This is great, although I'd suggest people steer clear of Strunk and White -- it's ancient and full of nonsense.

Could you provide an example?

This is a good place to start, and you'll find some defences on the same page:

https://roomfordebate.blogs.nytimes.com/2009/04/24/happy-bir...

This is a more complete set of criticisms.

http://www.lel.ed.ac.uk/~gpullum/50years.pdf

Also see Language log, which has many posts on the wrongness of S&W.

EDIT: If you're not familiar with Pullum, he's the co-author of the Cambridge Grammar of the English Language and probably the most respected grammarian alive today.

I found the comment section on the NYT blog more intriguing than the article.

The arguments brought forth by Pullum (I don't appreciate your appeal to authority) are completely ridiculous, examples:

> .. both authors were grammatical incompetents.

There are many ad hominems of this kind in the article.

> No force on earth can prevent undergraduates from injecting opinion. And anyway, sometimes that is just what we want from them.

Whether you should write subjectively surely depends on the type of text that you are writing. Providing style advice based on expectations of which urges undergraduates can't resist is laughable.

> "There were a great number of dead leaves lying on the ground" has no sign of the passive in it anywhere.

The book does not claim that this sentence is in passive form at all: "Many a tame sentence of description or exposition can be made lively and emphatic by substituting a verb in the active voice for some perfunctory expression as there is, or could be heard." (cited sentence follows)

Pullum also cites three works of literature from around 1900 that do contain the phrase none of us exactly once (?!) followed by a plural verb to make the point that none of us should be followed by a plural verb.

> "The copy editor's old bugaboo about not using \"which\" to introduce a restrictive relative clause is also an instance of failure to look at the evidence. Elements as revised by White endorses that rule."

I don't know where he found that rule; my edition of the book does not contain it.

For that article Pullum gets no respect from me. He set out to bash the book and its authors with ad hominem arguments, falsifications and far-fetched proof.

You asked for sources for an opinion on a subjective topic, you're not allowed to pull the "appeal to authority" card for being given exactly what you asked for.

Of course I am allowed to! Pullum being a respected grammarian does not substantiate the opinion that S&W is "ancient and full of nonsense."

"The Economist Style Guide" is excellent too.

Many years ago, i added a script to my blog to scan for certain words and throw an error if I ever use them.

Earlier this year, i was having trouble publishing my article. No matter what I did, it would simply refuse. I try locally with a sample text, it works fine. I spent hours testing, and blaming technology until I reread the error logs carefully:

> The word "Viviparous" is not allowed in this blog.

Why did you block "viviparous"?

Now I'm curious about the content of your blog…

As a female computer programmer called Julianne, I chuckled at point 18.

Robert has an awesome blog! Stuff like this makes me appreciative, but also jealous of people who can have the skill to put concepts and thoughts into simple and eloquent words.

It's been almost two years since I've started my own little corner of the internet and of course, it initially it was somewhat awful, but I'm also happy to see my writing (and that corner) improve gradually. I'd recommend to anyone to do the same!

Perhaps one of the more helpful / useful things I've read in the last few weeks.

My personal rule of thumb, which arcs over a number of the finer points, is:

"It's not what you say, it's what they hear."

So when it comes to humor, pronouns, self-deprecation, etc. you have to step back and crank up the empathy. Will they hear what you intended, or might you be misinterpreted / misunderstood?

Good input and definitely worth considering. Bookmarked :)

I really do dislike #18 though:

  "If you need a quick name for a generic fictional character, 
  consider using one from a culture or gender that you usually wouldn't.[..] 
  the cost of sometimes calling your imaginary computer programmers Julianna is zero."

First of all, there's a often a good reason you usually wouldn't: It's not realistic. And many readers will pick up on that and be annoyed. So the cost is not zero.

More generally, I think truth matters, and talking about the world as it is does not mean we don't want change. Pretending the world is somehow "better" than it really is does not help anyone.

It's not realistic to have a programmer called Julianna? I better let my friend know. I always thought her C++ was good, but I was obviously wrong.

Women can code. Most programmers are men

I think you're reading far too much into a blogger naming one of their fictional characters "Juliana"

Speaking of reality, I seldom come across Chinese/Indian names either, even though they make up a huge portion of the industry. Do you get annoyed by that as well?

  "I think you're reading far too much into a blogger naming one of their fictional characters "Juliana""

That's not what OP is saying, and it's not one blogpost. For a more general background check out this podcast (or hes book that I haven't read): https://www.jordanharbinger.com/jonathan-haidt-the-danger-of... (ok, not the same, but related)

That stands to reason, yes. It's not the case where I live though.

You're free to dislike it, but your conclusion "it does not help anyone" is objectively false.

It actively does help many people. There's a reason why marginalized communities care about "representation". Seeing people like themselves represented in the mainstream helps a marginalized individual see the path to an advanced level in an industry where they are a minority. It's inspiring. It keeps them trying despite meeting a roadblock that their other peers may not encounter. It may not be realistic, but representation is welcoming to minorities, and not really harmful to well-represented folks.

Just because it doesn't help you, doesn't mean it doesn't help anyone, which is a good thing to keep in mind in general.

  "You're free to dislike it, but your conclusion "it does not help anyone" is objectively false."

Well, you think that, but you don't actually know. Even if it helps in some ways it could have downsides (for the individuals or the society at large) making it a net loss.

  "Seeing people like themselves represented.."

Probably, and that's all fine and dandy. It's possible to do that without pretending. It's the misrepresentation of reality id dislike, not the diversity itself or even the highliting of it.

  "Just because it doesn't help you.."

That's very condescending. Also, I'm sure I'm in some minority if I look hard enough :P

Falsifying "it does not help anyone" is pretty easy.

Minority in any meaningful sense, which is what we're discussing here, is something felt. Seeing reality distorted toward your representation is something you can feel, because it's otherwise been off-kilter and absent throughout the rest of your spacetime, in a million little ways.

If you don't feel it -- or think you have to dig deep and look, as you suggest -- then, I love you, but you don't really understand what is being talked about here. That's not a barb or a take-down, nor anything the you should feel bad about, but it is a fact about the conversation you're trying genuinely to have.

No pressure, but this is a really good read! https://sindeloke.wordpress.com/2010/01/13/37/ It was the very first thing I accidentally came across back when I used to moderate a forum, before I realized there was anything to figure out about these conversations. I'm grateful for any consideration or attention you've given to this comment, as I know that we're all stupid-busy and distracted in this world of our. Cheers :)

> There's a reason why marginalized communities care about "representation". Seeing people like themselves represented in the mainstream helps a marginalized individual see the path to an advanced level in an industry where they are a minority. It's inspiring.

As a mixed race person, I couldn't care less about representation and find the obsession with it to be very weird. I can't relate at all. I have plenty of role models and their race, gender, religious affiliation, or sexuality means nothing to me.

Whose feelings matter more?

My guess is that as mixed race, you probably aren't marginalized (usually by "passing" as whichever is easier for others to accept you as). This is less about being a minority by numbers (Stanford grads are a minority...).

My point was also that representation of marginalized people doesn't harm you. Or do you get discouraged from pursuing your interests seeing fictional representation of marginalized communities?

Please don't trivialize issues that affect millions of people into a question of "whose feelings matter more?"

> My guess is that as mixed race, you probably aren't marginalized (usually by "passing" as whichever is easier for others to accept you as).

That's quite the guess. What's the difference between a black person and a mixed black person if they're both perceived as black (passing)?

> My point was also that representation of marginalized people doesn't harm you.

It depends. In a blog? No, even if I think it's silly. But representation has slowly creeped from "nice to have/ideal" to a mandate by counting up the people in the room , reducing them to group identity, and crying injustice if the numbers don't match national averages.

I think that it depends on audience. In the United States, you could use almost any culture's name and it would be plausible. But using e.g. an Irish name in a Saudi setting would require a bit of explanation.

Of course, a good author could use that twist to his advantage. But it could easily be overdone, more than a single "not like the others" characters would distract from the rest of the book if it is not central to the story.

Exactly. But no-one would argue that you should use Irish sounding names in your Saudi blog about Saudi people.

I have no issue with that section except that I doubt it will be universally applied. Julianna would also usually not be used to describe a person that sacrificed families and friends for money only to die alone and rejected, or Julianna the cheap antagonist that is a one-sided character of pure evil with zero depth. Reversing gender roles is usually only fun as long it falls within current cultural accepted norms.

There's tons of popular stories with an evil witch or stepmother...

Those are within the current cultural accepted norms. A evil witch is not evil because the woman choose it, but rather because she got possessed by the devil which is then driving actor. Evil which is rarely if ever used interchangeable with a "bad guy" antagonist.

Similar but different, a evil stepmother is not evil because she chosen to be evil, but rather always coupled together with context that is not interchangeable with the "bad guy" antagonist. Often this is used to demonstrate the downfall of over-protectiveness of ones own offspring over those of others.

Try replace any of the antagonist in TV or movies with "evil witch or stepmother" and you have not just changed the gender but likely warped the story. Thanos would look a bit odd as a evil stepmother (and how would his motive for the Infinity Stones work?), and Ebenezer Scrooge as the evil witch would change the meaning of Charles Dickens story.

Perhaps, then, the point is to annoy people and challenge their assumptions - if they are so annoyed to see it, perhaps this will in the more thoughtfully inclined people make them question why they find it so annoying.

A big idea in philosophy is that challenging our ideas generates some discomfort, so doing philosophy isn't a purely hedonist activity. I think at least in this case blogging could learn a thing from philosophy.

Although you have to be careful if you want to avoid being spanked for cultural appropriation or some such nonsense.

I prefer they just use gender neutral values. They, them, their. Avoid he, she, him, her. I've heard from a couple of folks that the "I have a friend, let's call them $NAME,..." really grates them. Skipping all of that is fairly trivial.

On the other hand, I have found making "they" more ambiguous about number to be grating. There are several forms of passive voice if they are needed. One could just get used to that.

It's late, and I don't have the energy to engage fully as I'd hope to in my better life, but I have to admit that I'm hugely disappointed in the substance of your comment. I'm sure you're a kind person, but this comment feels very callous to my sensibilities. I mean, I understand NOT understanding, but I fail to understand the confidence exhibited here. "readers will be annoyed"? What readers? What sort?

All I can assume is that maybe you and I have slightly different neurotypes, and that for you, somehow a factual sense of "truth" of the world is more urgent to represent than a harmless distortion in the name of unrealized justice. It feels like you're saying we shouldn't pre-emptively apply reality distortion fields on the way to a more just world. Because reasons. Sorry, I'm being testy, and I shouldn't be. I retract. Rather, it feels like you're saying we shouldn't because it might annoy neurotypes who are annoyed by it.

I should add that the sort of analytical neurotype who would be annoyed, is _actually_ having a shining moment of power through accessible tech knowledge, and so that makes it even more disappointing that this is how people with this neurotype are processing the world.

I'm not trying to come across as insulting. I'm just sad and frustrated about your views. You are entitled to have them, and I am entitled to be sad about that.

I've been writing for a while (few years, 200+ technical posts) and I have to admit, I don't follow most of the advice in that guide.

I pretty much go with:

Explain the why, show the how, make it as concise as possible, and whenever possible share shorties from real world experiences to make it relatable to a use case.

Also, up until writing this comment I didn't even realize I was doing the above. In other words, I don't set out to do that for every post. It just comes out like that naturally because most of my posts are based on experiences instead of forcing or trying to invent a blog post.

When I wrote one blog article a week I tried to write small pieces with actionable content.

Explaining render props in React.

Explaining JavaScript promises.

Explaining Webpack's offline plugin.

Often with code examples.

Thanks for posting that, it sums up a lot of points I always have in my head when I'm reading other blog posts but couldn't quite put my finger on it.

I really wish more people would especially take the advice of 11 and 12. Too many articles (Main offender being posts on Medium) are just made unreadable by using memes, gifs and swearing.

"""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"."""

Good grief. I don't have a thesaurus, but do they really give those as equivalents?

They give many (all?) alternatives. It's up to the writer to pick the word they want and usually inexperienced writers will pick a complicated word that makes them seem clever.

Also, "meretricious" doesn't mean clever at all. It means "apparently attractive but having in reality no value or integrity."

The only time I've seen the word in print was in the Sherlock Holmes books. Benedict Cumberbatch also used it once in BBC's Sherlock.

The post provides useful set of rules to follow when writing text. I want to add another one which I have found to be beneficial to my work: the write-good linter for English prose (https://github.com/btford/write-good). Using linters for writing text helps to systematically avoid transcribing everyday speech into written text. A habit which is widespread among people who write infrequently and without a peer review.

For me the best workflow is to pass a text document to the linter before the build/deployment procedure (after finishing all writing work!) and modify the highlighted entries. As a result I can see which sentences can be phrased in a way which improves their structure and ultimately the quality of the text.

I see a lot of great tips, and I believe that anybody who wants to touch up on their writing skills should bookmark this page, especially for later editing. For the tips about humour, I have to strongly agree. Badly executed humour just comes off as confusing or unprofessional (or both!).

My problem is editing. I’ll write an article, do a revision, then let it collect dust.

I don’t really believe in posting a long form article that hasn’t been reviewed by someone who understands the topic. I almost always leave out some not-so implicit knowledge or don’t expound enough on the more interesting points. It’s hard to address these types of issues without a fresh pair of eyes.

Most of my peers don’t know how to effectively get through a 10 page pdf and give only the most useful feedback. I feel like they are scared of being overly critical or think I’m expecting they invest more than a single read through and thoughts.

Maybe I’ll go back and give the third draft on some of these articles a try anyways.

A 10-page blog post is hard to digest for most people. If you break it in a few parts, your peers will be able to review them more easily, plus it gives your audience an incentive to come back (and also time for them to digest each piece as well).

For editing, one thing that has helped me is learning sales copywriting and direct response.

Copywriting forces you to trim the cruft and makes you take the reader's perspective. Their time is valuable so you need to be entertaining and engaging, AND you need to get to the point fast.

Tested Advertising Methods & Scientific Advertising are just some of the classic books about sales copy.

I don't know what topic you're writing about, but sometimes you really just need to get your work out there, despite it not being perfect.

I spent too much time writing and re-writing this article on procrastination (https://medium.freecodecamp.org/procrastination-sucks-so-her...) till I finally said "f--- it, I'm going to write this last section about finishing and shipping, then hit the publish button"

I’ll give copying writing a try! Letting an article sit seems like it might be needed for self editing. At least for me specifically.

> I'm going to write this last section about finishing and shipping, then hit the publish button"

Fitting. Nice article as well!

There is some good advice in here, some which I myself stumbled across after trial and error.

But 39 points?!

May be it's just me but whenever I see a list with over 10 items, I just get so tired when thinking about it. Ultimately it just gets filed away, never to be referred again.

I wish the post started out saying "9 things to get your writing style better" instead of "...39 ways to make your blog..."

In fact, even 10 is a long list. These days I try not to make lists more than 5 items long. Even shorter when it comes to list of things to do. Of course, each item can have some sub-items, if needed.

Edit: auto-correct mistakes and rewording

I was about to criticize you for not strengthening your attention span, that maybe sometimes you really do need 39 points... but on closer reading, I agree this could have been trimmed down. At the very least, 34 - 36 are variations of the same theme, and I'd simplify the entire section on humor down to just point 25: "It's better to be clear than funny."

But it seems like this was written as 39 points that help the author when they write, and it just happens that many of the points that help them are also useful to others. There's a lot of really good stuff in here & I wouldn't dismiss it just on length.

I suppose this is a natural consequence of the Twitter generation where attention spans longer than 2 minutes are for firmly in the realm of old people but no, if a 15 minute read gets you "so tired when thinking about it", the problem isn't with the author.

He should have said about the thesaurus: it's only for reminders -- don't use a word from it you would not have used; your readers probably won't know it either.

And, "Elements of Style" is a manual on how to lose confidence in your writing. Read Geoff Pullum's essay on what he calls "the nasty book": "The land of the free and The Elements of Style", http://ling.ed.ac.uk/~gpullum/LandOfTheFree.pdf

The best use of a thesaurus, is to replace a ten-dollar word you remember, with a one-dollar word you just can't seem to.

Let me just add my take here. You don't have to agree with it. But it seems unrepresentative for this to be the only remark about the Elements of Style.

I started to read the PDF you link to, "The Land of the Free." I found myself disagreeing with sentence after sentence. It doesn't help that he uses Strunk's first edition, which is very, very different from the famous second and third editions (my favorite). The edition he looks at is just Strunk. There is no White.

- Strunk and White did not write it together. Strunk was one of White's professors. Strunk had a homemade textbook. Strunk died. Decades later, White's publisher asked White to take Strunk's old handbook and rewrite and add some stuff. White did. The second edition. I can't remember if I have read this edition. I own the third edition and have read it over and over.

- When I look at the first edition online, it is much less inspiring. It has a lot more tedious tidbits and completely lacks the second half that White added.

- Even the third edition has stuff that I'm not sure is that important. But for me the overall gist was groundbreaking. Things like shorter is better. Don't try to be fancy and draw attention to yourself. Basically, writing is not some competition for fanciness. Many people think it is, but if you are trying to write for the sake of the reader --- instead of just to make yourself look good --- you will try to write efficiently and clearly.

- To me this was groundbreaking, because in not a single English class was this book ever mentioned, the overall teaching of all my classes was totally different, and the output by most of the world (blogs, textbooks, emails, whatever) seems to indicate that they have never read Strunk and White at all. "The Land of the Free" seems to say the opposite, that the Elements of Style is oppressing everyone, that most people are following it. Maybe in his neck of the woods, but not anywhere I have been.

It is clear that you were not paying attention to what you were reading.

Pullum compared Strunk's edition to White's rewrites, and demonstrated White's disgraceful changes to his teacher's better writing.

No, I just stopped reading after a while. At the beginning he says he used the free edition, which is only Strunk. Your verbal abuse only reinforces my opinion that something is amiss with the anti-Elements stance.

Great tips on writing, made me want to read more from the author and I found his post on WeSeeYou democratizing de-anonymization hilarious and thought provoking https://robertheaton.com/2017/10/17/we-see-you-democratizing...

Can someone expand on this?

> 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.”

Is the example meant to be douchey or not?

False humility. "I'm unqualified, except that I'm extraordinarily qualified."

To me it comes across as self deprecating e.g. I am very qualified in something but it isn't writing which is the relevant thing in this context.

Goes to show how tone can come across differently than you think.

Anyway aren't Oxford departments separate from colleges?

Thanks for the post. I really like point 2: "If you’re wondering whether you should write a piece at all, you probably should"

If the topic is something you've just learned, it can be helpful to write about it right then versus a week down the road. The topic will feel more meaningful, and your less likely to downplay your own accomplishments.

> 20. Alternatively you can also alternate between "he" and "she" and toss a coin to see who goes first.

Please, don't. Pick a single pronoun and stick to it. The alternating between he and she has left me confused for a minute on more than one occasion.

If you must be politically correct, why not use 'they' instead?

> Stay away from memes - they're just cliches propagated at the speed of Twitter. Never do anything to "all the things".

:tada: A standard technical post on Medium is a couple of meme-images with no context throughout :ok_hand:, and emojis absolutely everywhere. :partyparrot:

- Commented with :heart: by Mats

Loved this style guide. As a non-native English speaker, I think it's even more important to be mindful of your style, so you don't continuously use a limited vocabulary or small set of idioms.

I would have liked some good/bad example sentences for some of these.

I think number 26 was an example of bad humour.

One final item I'd add to this list: It is your own writing for your own reasons. Feel free to ignore any rule that you disagree with or just don't like, in particular if your write as a personal exercise, and not to try to build an audience.

I love Robert’s humanity shining through in this piece. “It doesn’t hurt you in any way, so just do it instead of arguing” is both trivial and rare. Today’s low-hanging fruits of moral advice, so to speak.

> strengthened property rights appear to have been responsible

Economists do not universally agree on the root cause of 20-21st century growth

That sentence really came out of left field.

"Here's how to write a blog post. [..] It's okay to poke fun at my particular ideology but you still have to admit I'm right."

>It's entertaining to poke fun at the downsides and pomposities of capitalism without denying the fact that strengthened property rights appear to have been responsible for much of humanity's progress in the last century or two.

What a bizarre ideological point to see in an article like this.

Reply on news.ycombinator.com