How to Write Blog Posts that Developers Read
49 points by mtlynch
49 points by mtlynch
The other option, of course, is to write for yourself. If anyone else reads them and gets useful information or insight, that’s a bonus. But simply putting your thoughts in order long enough to generate text is a good thing.
(Extra bonus if you go back to read what you wrote months or years later.)
Yeah I agree, just writing for yourself is probably the best way to start … It’s helpful on its own, to organize your thoughts.
I think the advice in this post is absolutely valid, but for some/many people the effort/reward may or may not be worth it (e.g. hiring illustrators, although I’d like to try that at some point)
Another perspective that I think is good:
I imagine my supervisor, a respected colleague, or a future employer reading my explanation. These imagined readers force me to ask myself honestly if I understand what I am writing. How do I know when a post is done? I write until I stop having significant questions, until my imaginary audience stop raising their hands. The end result is that writing forces me to acknowledge and then work through my confusion.
https://gregorygundersen.com/blog/2020/01/12/why-research-blog/
i.e. you can write for the biggest possible audience, or you can also write so that you will feel “not embarassed” if someone you respect later reads your post, etc.
Those are different goals, and both enforce some kind of discipline
Or you can write just for yourself, of course. I have definitely had the experience of Googling something, and then finding my own blog post from years ago, and then actually finding it useful, because I had forgotten a bunch of things :) That happened last year with https://www.oilshell.org/blog/2020/07/ideas-questions.html (i.e. it may not be readable to most people, but it helped me)
Yeah, I totally agree. I don’t think a wide audience should be everyone’s goal, and I think it’s useful to just write with the expectation that it’s useful only to you.
For me, there are certain posts that I’m satisfied if I’m my own sole reader (like remembering how to use Samsung’s crappy SSD utilities). Those, I’m very haphazard about and am not deliberate about my approach.
But a lot of my posts are articles where it’s important to me to hear feedback from readers, so I’ve learned to be more thoughtful about those and figure out ways to make them appeal to the audience I’m trying to reach.
The biggest mistake software bloggers make is meandering.
I hate this, not gonna lie. This idea that reading is only for getting information as quickly as possible is absolutely something a lot of developers believe, but it’s not how I read things, and not how I want to write either.
I do agree that if you’re trying to maximize reach, it’s a good idea.
Thanks for reading, Steve!
I hate this, not gonna lie. This idea that reading is only for getting information as quickly as possible is absolutely something a lot of developers believe, but it’s not how I read things, and not how I want to write either.
I feel like you’re arguing against a point I didn’t make.
I’m not encouraging authors to just blurt out all their information as quickly as possible. I’m talking specifically about the first few lines of an article. The author has to give the reader some reason to continue reading the article, or else very few people will stick around.
It’s fine to slow down and add some color once the author establishes to the reader what the article is about, but before that, the author has to win the reader’s trust and interest.
There are great software bloggers who defer getting to their real point, but they have that luxury because they have a loyal subscriber base who trusts them to deliver. But if you’re discovering an author for the first time on Lobsters or in search results, I’m assuming you don’t read every post from start to finish to see if the author arrives at any meaningful point.
I feel like you’re arguing against a point I didn’t make.
That’s quite possible! I was reacting to the general sentiment that I’ve seen around this, moreso than your exact words.
The author has to give the reader some reason to continue reading the article, or else very few people will stick around.
I totally hear you, and again, for your purposes here, I don’t think it’s bad advice. I just lament that a lot of reading is optimized for “total number of people who stick around” and not the art of writing itself. Or in other words, I feel sad about the narrowing of a variety of options into one single one. The “Mr. Beast-ification” of everything, if you will.
And I do do the same; you’ll often find my blog post titles are designed to be google-able, or that I’ll state my conclusion before I start the post. I do these things because you’re right, and when I’m actively trying to reach as many people as possible, I do them. But it makes me a bit sad sometimes, that’s all.
But if you’re discovering an author for the first time on Lobsters or in search results, I’m assuming you don’t read every post from start to finish to see if the author arrives at any meaningful point.
Sometimes! But I also acknowledge I’m a weirdo. I probably do have a higher tolerance for stuff like this,
I used to be - and mostly remain - in the “remove things from your text until only the core message remains” kinda camp. I still think it produces better text, generally, for the kind of information I want to convey - some technical idea, problem, solution, etc.
But my kids big enough now that we’ve been able to start reading longer books - The BFG, Narnia, Brothers Lionheart and so on - and.. yeah, damn. It’s something totally different, to be able to “meander” and paint worlds and emotions and ideas the way those authors can.
For me, cutting out everything but the essence is a way I know will produce useful text.. but it does leave out a whole world of things text can convey that does require meandering
There are great software bloggers who defer getting to their real point, but they have that luxury because they have a loyal subscriber base who trusts them to deliver.
Or they are simply good writers. You make it sound like readers put up with the meandering because there is a prize at the end. It can also be that those first sentences are interesting by themselves.
I quite enjoyed your post No Longer My Favorite Git Commit, for instance. And while there is perhaps no meandering, it is the kind of post where in the beginning you don’t really know what to expect, and you don’t know where it will end.
But the first paragraphs are interesting enough to keep reading. There is a story. If it was called “The inverted pyramid, a proven model for good commit messages” I probably would have skipped it.
Or they are simply good writers. You make it sound like readers put up with the meandering because there is a prize at the end. It can also be that those first sentences are interesting by themselves.
That’s a good point.
I looked at some examples of posts I had in mind to try to disprove you, but I realized I couldn’t. Like I love Paul Graham’s “What I Worked On” despite it being super meandering, and I was going to argue that I’d never read it if I didn’t already like Paul Graham. But then I just re-read the intro, and you’re right — I’d read it anyway because he’s clearly a good writer out of the gate.
In an earlier draft of this post, I had a paragraph about how the value you demonstrate can just be good writing:
The benefit can be just that it’s an entertaining article. I’ll read Matt Levine blog posts even when I don’t care about the subject matter at all just because he’s such a funny and interesting writer. But that’s a high bar, so don’t expect to skate by on your amazing writing.
But I took it out because I felt like people would just think, “Oh, the advice doesn’t apply to me because I’m a great writer.”
I feel like my position now is that it’s still a good rule to follow until you get good enough to know when to break the rule.
I quite enjoyed your post No Longer My Favorite Git Commit, for instance. And while there is perhaps no meandering, it is the kind of post where in the beginning you don’t really know what to expect, and you don’t know where it will end.
Oh, thanks!
I actually feel like that post matches my advice here, though. From the title + first paragraph (two sentences), I’m saying that I think everyone was wrong about this popular blog post. I don’t say immediately what I think was wrong, but the reader would (hopefully) know that the audience is software developers and the benefit is learning something about commit messages.
If you look at one of my older posts like “Automated Prosper Investing with ProsperBot”, I feel like I had a much worse ability to get to the point. Reading the whole first section, you wouldn’t really know who the post is for or why they’d want to read it.
But I took it out because I felt like people would just think, “Oh, the advice doesn’t apply to me because I’m a great writer.”
I wholeheartedly agree with that paragraph, but I understand your concern. It is not actionable advice. Perhaps it could have been included with a remark about how one can become a more interesting writer just by doing it a lot.
I actually feel like that post matches my advice here, though. From the title + first paragraph (two sentences), … the reader would (hopefully) know that the audience is software developers and the benefit is learning something about commit messages.
That may be true. It clearly explains that the audience is software developers. But that is not what made me want to continue reading. Looking back, I think it were the words “whimsically detailed” in the first sentence that did it for me. They tell me that not only is there some development (first you liked it, but you now look at it differently), but also that you have the emotional distance to tell what happened in an entertaining way. Like we are in a bar, and you are going to tell me a funny story. This drew me far enough in to read that original commit, etc.
Looking back, I think it were the words “whimsically detailed” in the first sentence that did it for me. They tell me that not only is there some development (first you liked it, but you now look at it differently), but also that you have the emotional distance to tell what happened in an entertaining way. Like we are in a bar, and you are going to tell me a funny story. This drew me far enough in to read that original commit, etc.
Oh, that’s interesting. Thanks for sharing such detailed feedback!
It’s rare for me to hear exactly what element of an article drew a reader in, so it’s fascinating to hear your thought process.
I don’t necessarily think it’s about getting information as quickly as possible. Much of the time the meandering is unintentional, uninformative (devoid of any substance), and/or exists only to pad the length of a post in a misguided attempt to make a post seem more “serious”.
Writing succinctly is more difficult than not. If the meandering makes it more difficult to get the point of the post, it’s actively harmful. At least for me, this is the case with a lot of writing on the web.
Writing succinctly is more difficult than not.
I don’t disagree in some cases, but I also don’t think succinctness is always a virtue.
Then again, I got accepted to English graduate school, so.
It depends. If I’m trying to figure out “how do I do X” and the answer is in someone’s blog, I don’t want meandering any more than I want it from a StackOverflow post. If I’m just reading someone’s thoughts, then meandering can help “set the stage” or provide insight.
Not following this advice makes for more interesting writing though.
Perhaps one can attract more views this way, but the posts that “squander their first seven paragraphs on the history of functional programming and a trip they took to Bell Labs in 1973” are the ones that I actually enjoy and remember. Generic ‘optimized’ cookie cutter posts are instantly forgettable.
I guessed that Lobsters would bristle at this post because
(although I didn’t see any comments about clickbait)
Look, I thought the same things when I clicked the link. There is a kind of pureness to writing for writing’s sake. Just put your brilliant ideas on the page and let them speak for themselves, readership be damned. You don’t need to waste your time appealing to the 30-second-attention-span generation or SEO.
But I find my conceptualization of this “purity” naive. To me, writing is about communication. And if you cannot communicate your idea effectively, then you have written it poorly. I posit that we do not naturally write in the form most amenable to communication. If this were true, OP would have no advice to give. (BTW, I believe a large part of communication is aesthetics: I’m not asking you to find the lowest Kolmogorov complexity representation of what you want to convey)
With writing advice it always amuse me when someone present an example of what to do and I find myself preferring the bad example. I immediately hated the article about his 46k website redesign because of the clickbait title. I wouldn’t have skimmed it because I wouldn’t even have clicked on it. That title just reeks of self-promotion, low value content and popups asking me to subscribe to some dumb newletters. At a glance, the cypress article looked much more interesting.
This post in particular has particularly good advice if you’re actually seeking raw views. No real notes there.
There are many comments in this thread saying to explicitly go against the advice in this post though. This is def a community that appreciates the niche, and appreciates posts with a more personal angle, I have observed. That’s what I love about lobste.rs. So, it’s just a matter of what your goal is.
Probably goes without saying, but this is good advice for technical writing in general. Lots of design docs at work could benefit from getting to the point.
I want to, at least partially, live and write by this advice.
But I’ve found myself mostly incapable of avoiding meandering side notes, and editorialist or even pseudo-poetic comments on even the most technical and dry of topics. I think I should start writing footnotes and maybe skippable extra credits sections.
A bit off-topic, I use a summarizer chrome extension¹ to give me a TL;DR of any article to get the gist of it, and if I find it interesting, I read the article itself. It’s specific to Claude and requires an API key, but it’s totally worth it.
Here’s my prompt:
You are a chrome extension for summarizing web pages. Give me a TL;DR of this article in 80 words or less (without saying “TL;DR” at the beginning, or any leading wording that is not part of the summary). Use markdown bold syntax to highlight important keywords (or key phrases), single backticks for inline code words, and code fences for code blocks. The summarized text should fit in the Chrome extension pop-up window.
¹https://chromewebstore.google.com/detail/summarize-and-translate-w/ciikfihmdpcbmehhggahlgljimikipbm