How to write blog posts that developers read
156 comments
·March 28, 2025marginalia_nu
hk1337
> The inverted pyramid is almost always the correct format for your text. I often put the tweet-length version of the post in the title or first paragraph. Get to the point quickly, then elaborate. Means you can bail out at any point of the text and still take home most of what mattered, while the meticulous crowd can have their nitpicks addressed toward the end.
This sounds similar to what I was taught, in high school ~30 years ago, about journalism. When you write an article for the paper, the first sentence should have the who, what, when, where. The reader should be able to get the basic, relevant information from the first sentence then start giving more details as you go along. This is not only for the reader but to make it easier for the editor if/when they need to cut an article short then they can just cut text from the end.
ZYbCRq22HbJ2y7
> what I was taught, in high school ~30 years ago
They should still be teaching it? I don't think much has changed? I went to school a decade ago, and during that time we still wrote essays following these guidelines.
https://owl.purdue.edu/owl/subject_specific_writing/writing_...
https://owl.purdue.edu/owl/general_writing/academic_writing/...
https://owl.purdue.edu/owl/general_writing/the_writing_proce...
---
Also, there are many different forms of writing. People write in forms other than argumentative essays, etc.
strogonoff
The inverted pyramid principle is like a cold shower: it feels harsh at first but is overall good for your fitness as a writer, as it requires you to 1) understand your own main idea and distil it, which is not always easy if you are not writing a factual news story, and 2) not indulge and get to that distillation immediately, allowing the reader to stop whenever they reach the level of detail they want, which may not jive well with a “free” ad-based publication model but is absolutely reasonable in a subscription-based model (which is, I suppose, where the rule originated).
It is among the few useful things I learned at the university.
ghaff
It may be worth noting that there are historical reasons why newspapers in particular used that format, especially wire copy. The idea was that, in layout, typeset stories could be cut at more or less an arbitrary point. Magazine stories are much less likely to follow this exact format although they still tend not to completely bury the lede.
eichin
> cut at a more or less arbitrary point
Cut literally - I worked on a student newspaper (with professional phototypesetting gear, comparable to the city papers - AKI Ultrasystem) and second-tier "filler" content was just set in a single long column, then pasted up on the layout boards (hot wax as the adhesive) and then trimmed when it ran out of space (with an x-acto blade.) Reading that class of content was kind of optional for the layout editor, at least at 10:30pm when trying to get the boards out the door for an 11pm press deadline...
jvanderbot
Ok, but isn't pyramid the point at the top, and inverted pyramid is the point is at the bottom? Have I been looking at the wrong pyramids my whole life?
ithkuil
No you looked at pyramids the right way.
The disconnect here is what is the meaning of the "width" of the triangle/pyramid in the analogy.
The idea in the journalistic inverted pyramid concept is that the width of the pyramid correlates to the importance of the information.
So you start first with the most important information (the base of the pyramid, at the top) and then as you continue you fill in the details that may be interesting and necessary to support the important information, but not necessarily important on their own (the tip of the pyramid, at the bottom)
forrestthewoods
> the first sentence should have the who, what, when, where
I utterly despise modern long form journalism which does not establish any of these things until 1/3 through the article. It’s infuriating.
chatmasta
It's not just long form journalism. The basic five-paragraph essay, taught in every school from elementary through university level, violates this principle. When you're learning to write, there is an implicit assumption that you have a captive audience — even if it's limited to your teacher — who is forced to read your work. So there is generally insufficient emphasis on "getting to the point." Instead, you're taught to "grab the reader's attention," with an exciting sentence or visual anecdote. That's what you're seeing in long form journalism that usually starts with some narrative description of a central character in the story.
Whereas in the real world, you are competing for attention, and nobody has to read what you write. So if your goal is to convey information, you better get to the point. But if your goal is to tell a story, then what's the rush?
tehjoker
The articles were intended for you to read. If you find them annoying, maybe they weren't written for you.
ako
I feel like most news articles I read miss the why, just like your first sentence.
miki123211
But aren't you happy when you finally learn that John was wearing Khaki pants and sipping a Latte that he just ordered at a starbucks? /s
pansa2
> The inverted pyramid is almost always the correct format for your text.
Do you find this conflicts with "offering an interesting story that resonates with the reader"?
For example: Using inverted pyramid to describe a problem and my solution, I'd structure my writing as "here's a problem, I found this solution, using this method". Whereas a story would usually be told in chronological order: "here's a problem, I tried these methods, and came to this solution".
Or is it possible to both have your cake and eat it? Tell a good story after giving away the ending?
ketzo
Particularly with technical writing, I think you can definitely get away with both.
“How I Reduced My Postgres Query Latency By 100x With A Single Index”
Even in the title, I can tell you the punchline (if you wanna make your DB access faster, use an index!)
but an interested reader still wants to figure out how exactly your solution works, and you can tell them some interesting details along the way
“just enforcing unique constraints does help certain data types, but it’s not a big performance boost most of the time”
while finishing on the kicker
“Since my hottest endpoint by far was for individual users querying orders which were still ongoing, I created an index on the user field for the orders table, and included a status filter in the index, which took p90 latency from 10s to <100ms!”
kqr
I have noticed that when I wrote blog posts they tend to fall in one of the two categories. Sometimes I'm trying to share an insight, in which case I make sure not to bury the lede[1]. Sometimes it's the journey to the insight that matters more than the insight itself[2], in which case the narrative take precedence, even if it buries the lede.
In some cases it is possible to combine both, by using the storytelling formula that starts describing the outcome and then traces back to how things ended up that way.
[1]: The lede is in the title, even! https://entropicthoughts.com/code-reviews-do-find-bugs
[2]: This is all meandering discovery. https://entropicthoughts.com/deploying-single-binary-haskell...
marginalia_nu
You can have other formats as well, and the one you describe can work out, though you're at serious risk of losing the audience before the big payoff.
I think what matters the most is that the reader can tell quickly whether the text is interesting.
You could start by e.g. describing a mystery, and then proceed to reveal the truth later, this sometimes works, though if the payoff isn't there, readers will feel cheated.
RicoElectrico
Good story defends itself even if you know the ending.
sunshowers
There's a tension here but I don't think it's a fundamental conflict.
rsync
“Inverted pyramid …”
I developed a writing format that I call an “iceberg article”:
https://john.kozubik.com/pub/IcebergArticle/tip.html
… which qualifies as an inverted pyramid but with some additional attributes.
Noumenon72
I built up a lot of expectation that this article was going to be self-referential and link to a hidden well of info. At the very least it ought to link to one example of such an article so we know you aren't describing something theoretical.
rsync
It is exactly what you expected - click the "body" link and you'll see the entire topic fully expanded:
ddejohn
> Images should above all never be funny.
Why on Earth not? Maybe a blog about conflict in the middle east isn't the place, but a blog sharing stories about the tech industry? Surely some humorous screenshots will add to the experience.
Obviously just throwing in random images totally unrelated to the subject matter would be a huge turnoff, but I cannot think of any reason why you'd take such an absolute position on something so low-stakes.
dwedge
I agree with the point and didn't realise it until I read this post. Whenever I see a funny image or comic in a technical post it always feels a bit like it doesn't quite belong there, like someone had a quota for humour. It feels a bit like the author isn't confident with their message and acted like a conference speaker throwing in a bad joke for some easy laughs.
It also breaks the flow. Reading from long form text and then skipping to image and parsing the text breaks the mental flow, for me at least, and there never seems to be a clean place to do it.
marginalia_nu
You get this jarring tonal whiplash when you add funny images to an otherwise serious text. The images detract from the message you are trying to convey. It also risks triggering a skimming behavior where the reader is just skipping between the images.
It also appears insecure and juvenile, as though you're not fully confident that what you are saying will stand on its own without attempts at comedy, and ironically raises questions about the age and experience of the author.
Of course there are exceptions, but as a rule of thumb, I would strongly avoid this pattern of communication.
wavemode
It sounds like your problem isn't with funny images, but tonal mismatch. In that sense I agree with you - if the article's tone is lighthearted, use lighthearted images. If not, then don't.
I would expect the "a monad is just a monoid in the category of endofunctors, what's the problem" article to include humorous images. I would expect a serious tutorial about monads to not do so.
mtlynch
You're kind of moving the goalposts.
You went from "Images should above all never be funny," to "You get this jarring tonal whiplash when you add funny images to an otherwise serious text."
Yeah, if a post's text is 100% serious, then yes it would be jarring to insert funny images. Nobody's suggesting you do that, though.
>It also appears insecure and juvenile, as though you're not fully confident that what you are saying will stand on its own without attempts at comedy, and ironically raises questions about the age and experience of the author.
This comes across to me as strangely judgmental and narrow-minded about what good technical writing is.
Joel Spolsky is, in my opinion, the best software blogger of all time. His posts often integrated humor, and I think it definitely heightened rather than detracted from his writing.
Look at the bloggers who are most popular on HN: Paul Graham, Julia Evans, Simon Willison, Rachel Kroll, Terence Eden. All of them often use a lighthearted style and integrate humor, often with humorous images as well.
roland35
I think the key is to be your authentic self. If you’re trying to force being funny it comes off poorly.
greenchair
it decreases authority projection
sunk1st
Wouldn’t that be a regular pyramid? In what sense is it inverted?
tantalor
It's a bad metaphor.
In the "inverted pyramid" the most important information (which should come first) is represented by the base, which is the biggest part of the pyramid and holds up the rest of the pyramid. In a sense, it is the foundation, so you have to "get it right".
The analogy is "base = big = foundational = important"
Personally I think that's confusing, because you just as easily say the tip of the pyramid should represent the most important information, which should be conveyed concisely and without extraneous detail or background.
In that case the analogy would be, "tip = concise = main point = important"
irrational
That is confusing. In my mind, the tip of the pyramid is the smallest part of the pyramid, just like the brief overview at the beginning of the post is the smallest part. The base of the pyramid is the biggest part of they pyramid, so that is the bulk of the post where it goes into detail.
kens
The "inverted pyramid" first described a visual pyramid, not a conceptual pyramid. I found an 1887 article in Time magazine on journalism, describing the inverted pyramid structure. Specifically, the top of a newspaper article (the display, summarizing the article) consisted of not just the title, but multiple lines of different sizes. First, the title in large capitals. Next, a line of small capitals. Finally, three, four, or more rows of smaller type arranged in the form of an inverted pyramid.
That is, the lines in the heading got progressively shorter, making a visual inverted pyramid, with the most important information first.
Later, the "inverted pyramid" term described the structure of the entire article with the most important parts first, but the metaphor does seem backward.
https://books.google.com/books?id=rNaEw8DwatwC&pg=PA154&dq=%...
Galanwe
That seems intuitive to me, but I guess it depends how you picture it.
I think of a pyramid from the ground up, so a dense base followed by a thinner top.
A inverted pyramid would be thin first then dense and large.
When reading though, you go from top to bottom, so if you're more visual instead of time based, you may see it the other way around.
jasode
> In what sense is it inverted?
The triangle is upside down:
azornathogron
It's funny because from that diagram I really don't see any particular relationship between the shape and its content. You could draw a regular pyramid with three segments and write the same labels on it and it would make just as much sense to me.
If anything a regular pyramid makes more sense to me: you want the smallest/narrowest useful description at the top and then you gradually expand on it as you go down, providing more (wider) context and detail for the key information.
Edit: Of course, it's a widely used term and good to understand in that context; the Wikipedia link is useful.
marginalia_nu
It's not my name for it, but an established term for the style, so I wouldn't know.
I would note that most pyramid metaphors tend to be kind of lacking. Test pyramid, food pyramid, etc.
mvkel
This works for blog posts, certainly. But it falls apart if you're doing anything even slightly long form, or have multiple points to make.
It's also why LinkedIn posts all sound the same.
"It seemed like any other Monday. Little did I know, it was going to be the day that changed my life forever..."
"Marketing isn't about getting the most traffic. It's about converting the most traffic. A thread:"
yesfitz
Why do you think the inverted pyramid doesn't work for longer form?
If you have multiple points that don't both support a larger point, they should probably be split into two separate essays.
Your first example could be the start of an inverted pyramid if the thesis of the post is how the Monday was just like any other. But the next sentence dashes that notion.
The second example could be an example if it quickly follows up with the ways to convert traffic, but better to lead with the novel way(s) to convert traffic, then follow up with why conversion is more important than generation.
PeterFBell
To :+1: this, even if it's a book - there is a central thesis - a headline and a sentence that tells you whether you want to read more. "Your pet could save your life" - The six surprising reasons that people with pets live longer than others.
Then each chapter has the same: "Getting in touch" - why stroking your cat soothes your body. Etc
You may even have sections within the chapters and each can follow the same format.
Thousands of years ago it was enough just to write down stuff you've learned, call it "Meditations" and hope people would still be reading it in the distant future.
Now if it's just "stuff I've learned about coding" or "things that make me happy" you're going to need an extremely strong hook to tie that together and build an audience.
So start with a single thesis and decompose from there. Inverted pyramids all the way down :)
mvkel
To me it just gets repetitive. After the first one, my brain recognizes the pattern. If chapter 1 starts with a bang, then fills in the blanks, then chapter 2 is structured in the exact same way, it feels formulaic; not good writing
xmprt
The two examples you gave seem like bad examples of inverted pyramid. Inverted pyramid doesn't leave you hanging. It's not clickbait. It should be the case that within 1-2 sentences you can mostly understand what the rest of the article is going to be about (like an abstract).
rzzzt
It doesn't work for me, I get a little angry each time I read the above-the-fold five word hot take.
mtlynch
Thanks for reading, Viktor!
>I'm less bullish on images, unless they are profoundly relevant to the text. Illustrations for the sake of having illustrations are no bueno in my opinion. You want to reduce distractions and visual noise.
I'll respectfully disagree on this one. You can overdo images, but I think readers find a wall of text intimidating and visually too boring, but this is a matter of taste.
>Images should above all never be funny.
I strongly disagree with this. It's like saying a technical blog post should never have jokes.
Why should an image never be funny?
I think you absolutely can mix humor and useful technical insights. xkcd is probably the best example, but there are lots of authors that complement their writing with humor, both in images and in text.
marginalia_nu
I think you can be funny, but only in posts that are made to be funny. xkcd is primarily intended as comedy and that's fine.
Mixing humor into serious communication comes at the expense of authenticity. It's difficult to know what an author really means when they mix attempts at humor into the writing (and this is often deliberate, if someone makes a particularly spicy political remark, it's usually in the form of a joke, in order to shield from potential backlash). Overall it's a style of writing that feels sophomoric and insecure, as though the message itself isn't enough so there's a need to crack jokes to compensate. This successfully distracts from the message you're trying to convey, ... at the expense of clarity.
lapcat
> Mixing humor into serious communication comes at the expense of authenticity.
Only if you're authentically humorless. ;-)
n0tquitehere
Humour can absolutely feel forced and insecure, however it can be a great tool to help deliver a point. Done well humour can help with the flow of a presentation or text, done badly it jars. You have to know your audience and keep your humour on topic: "street jokes"* are almost never going to work in your favour.
I read a really interesting book* about the topic a while back where the authors delve into why humour works and how to find a style of humour that works for you. Unfortunately there are places imo where they fall into their own trap of trying too hard, but honestly it serves to prove the point.
* https://www.urbandictionary.com/define.php?term=Street%20Jok...
ThrowawayR2
Steve Yegge's (in)famous Google platforms rant and his other early essays is a counterexample I would think. It was taken down long ago but there's an archived copy at https://gist.github.com/chitchcock/1281611 .
bookofjoe
For sure a HN comment should never have jokes: instant downvotes. Watch this space...
mtlynch
I know you're kidding, but I think it's actually more nuanced.
Jokes in HN comments typically don't play well if the whole point of the comment is to make a joke, but if you make a joke in service of a substantive point or attach a joke to an otherwise meaningful comment, there's usually a good response.
I've come to appreciate HN's cultural norms around jokes because if you compare discussion to something like reddit, the top comment is often just a joke or a pop culture quote and then a massive thread of people just talking about the joke or reference rather than the actual story. I think HN's norms do a better job of fostering curious discussion.
SwtCyber
Interesting take on images. I've found them helpful when they clarify something (e.g. architecture diagrams, before/after screenshots), but yeah, filler visuals or jokey memes can definitely cheapen the tone depending on the audience.
stephantul
Counterpoint: writing blog posts so that they are read by someone else completely defeats the point of writing for 99% of people. I do not mean to say that this the advice in the post is bad advice, just that if you focus on being read (i.e., checking rankings on HN, only writing articles that don't exist yet) you probably just will just stop writing at one point, because most of the stuff on the web just isn't read, and writing just to be read is probably not very motivating.
Writing, even if no one reads what you write, is super valuable, and fun! Writing something down is to structure your own thoughts so that you learn more about the topic and about yourself. In my experience, publishing a piece of your writing just ensures that you double check your thinking, but most of the benefit is learning more about what you intend to write about.
So here's my advice: just write posts on what you think is interesting on your personal blog. Don't install analytics, just write it down, publish it, and put it on your LinkedIn. Someone will see it someday and will like it.
mtlynch
Author here. Thanks for reading!
>Counterpoint: writing blog posts so that they are read by someone else completely defeats the point of writing for 99% of people.
I think it's totally fine for authors to write for themselves, but I think the number of authors who have that goal is far lower than 99%. Maybe 5-10%?
For almost every author I've spoken to, they get satisfaction from people reading what they write. It doesn't have to be millions of people, but I don't think most people find it satisfying to spend hours writing an article for it to only reach a single-digit number of readers.
So, I don't think it should be every blogger's goal to find a wide audience, but if it is, I think the recommendations in OP will be helpful towards that goal.
tasuki
You're obviously very good at writing things that get read by many people. It seems to be a very high priority for you.
The link on your website says "Write Blog Posts that Developers Read". I'd have expected that to explain _why_ writing blog posts that developers read is worthwhile.
> It doesn't have to be millions of people, but I don't think most people find it satisfying to spend hours writing an article for it to only reach a single-digit number of readers.
I write a blog that gets read by no one. When I publish a blog post, I don't check how many people read it. The blog has no particular topic, just whatever random thoughts pop into my head. Yes I'd like to improve my writing, so I can formulate my thoughts better. But I'm a little suspicious of anyone who thinks reaching a big audience is so obvious a goal it doesn't even require explaining why.
[Edit]: Ah, I think I get it now! You write about how to write so that people read your blog. And you're good at it, which leads to many people reading your blog. Naturally, your readers are people who want their writing to be read more. You interact with your readers, and that's why you think people write blogs with the goal of them being read.
mtlynch
>The link on your website says "Write Blog Posts that Developers Read". I'd have expected that to explain _why_ writing blog posts that developers read is worthwhile.
The post is aimed at people who want their writing to reach more developers. If they've reached the article based on the title, I assume they already want to reach more readers, so I don't think it's worth explaining at that point.
If I clicked an article called, "How to vertically center a div using CSS" and the article explained why I might want to center a div, I'd find it kind of strange and not what I want to spend my time reading.
>I write a blog that gets read by no one. When I publish a blog post, I don't check how many people read it. The blog has no particular topic, just whatever random thoughts pop into my head. Yes I'd like to improve my writing, so I can formulate my thoughts better. But I'm a little suspicious of anyone who thinks reaching a big audience is so obvious a goal it doesn't even require explaining why.
I think that's fine, and I support you doing that, but it just means that you're not the audience for this particular post.
I've published several other excerpts on the book's website that are about craft rather than strategy for reaching readers, so you might be interested in those.[0]
stephantul
Thanks for responding. I guess I was getting at the fact that 99% of people won’t consistently hit high reader numbers. So to pick this as your goal, or starting point for an article, is dangerous because it just leads you to stop writing at some point.
But fully agree on the advice if the starting point is getting a lot of views/front page.
mtlynch
>I guess I was getting at the fact that 99% of people won’t consistently hit high reader numbers. So to pick this as your goal, or starting point for an article, is dangerous because it just leads you to stop writing at some point.
Oh, but I don't even think the numbers have to be "high" for this advice to apply.
Like I talk to bloggers who don't really have a strategy except to just keep writing and submitting to HN or reddit, but they don't get traction, so they get discouraged and give up.
The point I'm hoping to get across to those bloggers is that they can find readers if they think through from the beginning what topics they want to write about and what channels allow them to reach readers that match. That technique works even if you just want a few dozen people to read your posts.
Retr0id
I find writing useful for its own sake, but even the "writing for myself" is more useful if I act like it's intended for someone else.
SwtCyber
I think, writing for yourself first, without worrying about views or rankings, is where a lot of the real value comes from
dynm
I reckon if you wanted to choose just a single rule it should be, "Write something that you yourself would actually read." The problem is that our brains are designed to sort of lie to us and tell us that what we've created is amazing when in fact we'd never actually read it if someone else had written it. If you can find a way to be objective and see your own writing as the far-from-perfect mess it actually is.
(In principle, you could use "write something that someone else would actually read", but I think this is much harder, because it's much harder to know how other people would react! If you yourself would read it, well, we aren't that unique, lots of other people would read it too.)
Also, props for this stark picture of reality: https://refactoringenglish.com/chapters/write-blog-posts-dev...
kqr
> I reckon if you wanted to choose just a single rule it should be, "Write something that you yourself would actually read."
This is a good rule, and I think the first test of it is "have you suffered through proof-reading it three times?"
The garbage people write when they don't even proof-read it themselves! I find that by the third time I read through my writing (ideally spaced out over a few days) I have worked out most of its kinks.
And read it out loud! If you cannot, at least get an AI voice actor to read it for you. You catch so many more problems that way.
bluGill
That is always what I hate about discussions like on HN, reddit, and the like: if you don't respond "fast" nobody will read it. By rights instead of hitting the reply button in a couple minutes I should put this reply in some queue, and review it several times over several times and then hit reply. However that means my insightful (lets assume insightful, though that isn't always a given) reply has waited until this is well off the front page and so nobody (except maybe the person I'm replying to) will notice.
Instead what I do is glance over things - but that mostly means I fix anything my spell checker has flagged. I know from experience that if less than several hours haven't passed I will not see all the things that don't make sense - they make sense in my mind and I know what I meant really meant. Several hours/days later I will see just how impossible things are to understand. (I'm now going to press that reply button, I hope this all makes sense to you..)
mtlynch
>And read it out loud! If you cannot, at least get an AI voice actor to read it for you. You catch so many more problems that way.
Definitely agree.
I initially included this in the article but I took it out because I wanted to limit to just advice I didn't see covered much elsewhere, but I always tell people to read their writing aloud.
I don't think an AI voice would get most of the benefits, though. For me, a lot of what I notice when I read my writing aloud is that I find myself naturally finishing sentences in a way that departs from what's on the page. And however I finished the sentence naturally almost always is a better rewrite than what was originally there.
rikroots
> The problem is that our brains are designed to sort of lie to us and tell us that what we've created is amazing when in fact we'd never actually read it if someone else had written it.
You've just described 98% of my poetry output. Luckily I consider this to be a feature, not a bug, and shall continue to churn out more poetry regardless of what the rest of the world thinks.
SwtCyber
I really like the "write something you'd actually read" rule
swyx
> "write something that someone else would actually read"
you nail the nuance - most people i find are really bad at stepping outside themselves and objectively judging why other people should be interested
AmazingTurtle
Ironically I opened the post, read the headlines, deemed it uninteresting and went along with other HN headlines.
edit: I think I read HN comments more than HN articles. Interesting
mtlynch
Author here.
Your comment suggests that you at least read the last section. : )
But still, that's headings and structure working as intended: You skimmed it, got a good sense of what it's about, and decided it wasn't for you.
I'm assuming that if I had presented the same information in a different way, it still probably wouldn't have appealed to you if you could tell from the headings that you weren't interested.
ddejohn
> edit: I think I read HN comments more than HN articles. Interesting
Nothing wrong with that, in my opinion.
I always check comments first before clicking the link, unless it's something I'm knowledgeable about and/or interested in and already know I want to read. It saves a lot of time.
nextts
Sample size 1. To increase to 2:
I opened it, read enough to establish this author knows what they are talking about and bookmarked it to read properly before my next blog post.
Had they told me the blogging equivalent of their intergenerational nanna's spaghetti recipe first I may not have done that.
rednafi
Steve Ballmer never diversified his Microsoft stock like Bill Gates did. But it made him an immensely rich guy—currently richer than Gates himself. Now, does that mean picking a company and going all in is a good idea? Probably not.
I’m all about improving my writing to be useful to others. However, diversifying my content to attract a broader audience usually results in the most vapid, formulaic, clickbaity articles. No matter how many eyeballs they get, I don’t get any pleasure reading or writing them. And writing is how I slow down and shape my thinking. I like doing it for myself, not for the audience. But I deeply appreciate however many readers I get.
Hacker News has a pattern of articles it favors: Zig, Rust, why Go isn’t for the “smart” developers, arcane PL theories, nostalgia about some Lisp variant, why you should blog, small internet, and so on. Ninety percent of the time, they’re forgettable. I usually learn more from the comments than the articles themselves. I also don’t want to write just to capture a certain kind of audience.
I mostly write about things I’m currently working with or interested in. I tend to write something I think past me would find useful—and future me might, too. That’s very different from shaping your writeups for the audience. My stats aren’t impressive as the author, but I do get a few thousand monthly visitors to my blog[1]. I’ve had job offers because a recruiter came across one of my posts somewhere. It’s a different way of thinking about writing, but I’m immensely happy with the result.
[1]: https://rednafi.com/
abbadadda
Any examples of this? > why Go isn’t for the “smart” developers
MartijnHols
So long as your article has a decent enough structure – which this article makes it seem is the only thing that matters – I reckon there are two ways to make blog posts that developers read and share;
1. make so many of them, you'll repeatedly hit gold eventually
2. go the extra yard with research and/or effort
The intro's "The developer had interesting insights" makes it sound like they failed blog was full of opinion pieces. Very few opinion pieces succeed, but they're the easiest to write (i.e. the first category). It might work for some people, but for us unknowns, nobody really cares. Go the extra yard and make it interesting by doing a deep dive of the subject.
I've fully focussed on the second approach. As a consequence, each article takes a lot of time to complete, so I generally don't finish more than one per month. I try to make them all something I can actually be proud of (which is quite a challenge), and then I spend a lot of time tweaking the structure, making things less verbose, and improving scanability – I rely on making sentences bold a lot for that. I try to use relevant images, but I find actually helpful ones are hard to make for developer content. While hiring illustrators is a good idea, I doubt many writers are willing to pay for that.
To make my articles more interesting, I try to make a custom component for each article to spice it up and slowly grow the component library I have available for my blog. It doesn't always work though – for my last article I spent several hours building an easter egg that only 22 people (<0.1%) interacted with it.
CuriouslyC
I would absolutely not go the extra yard with research/effort until you have an audience for your blog. I've seen plenty of well thought out, in depth posts get zero traction because the blog wasn't established, and plenty of off the cuff short brain dump posts from established blogs get front page HN traction.
MartijnHols
This wasn't my experience. Hacker News felt surprisingly welcoming as soon as I upped the depth and reduced the opinion.
There are some areas I noticed Hacker News isn't very interested in, such as web accessibility (other platforms picked that up much better), but I think that has more to do with the not-as-exciting subject than the writer/blog.
kristopolous
I spend something like 5 or so months on each one I write. I'm aiming for substantive work with original research to be an actual contribution.
jeremy_k
> I've fully focussed on the second approach. As a consequence, each article takes a lot of time to complete, so I generally don't finish more than one per month.
This is what I've been running into. My approach comes out of writing a bunch of code or re-writing the same sort of code across multiple projects and realizing it would be useful to share. Next I'll dump all the code into a blog post and have to start formulating what the structure of the post will be. What content do I need to add to support my claims that this code is correct (or correct enough to use)? Add in time to research alternative approaches to the code, research and write about the alternatives.
I've found that I'm proud of my finished articles but it takes awhile to get them written. I'm in the midst of one that I've kind of hit a writers block on because I have a fair bit of research left to do. I haven't been motivated to do the research and write up the findings. However, I feel like thats normal and I'll get back to it at some point.
mtlynch
>So long as your article has a decent enough structure – which this article makes it seem is the only thing that matters.
Author here.
I hope I didn't give the impression that structure is all that matters, as that's not what I believe.
I think all the usual advice about choosing an interesting topic and writing well apply too, but I tried to focus in this article on blogging advice I don't see people discuss.
swyx
fellow writer here
you can have your cake and eat it too: TLDR, create a multi tier system
do a bunch of short form posts and see what gets abnormal traction from others / gets referenced by YOU more
THEN you invest the time to go the extra yard
this way you dont overinvest in what isnt popular and you also get multiple "shots on goal"
xena
TBH as someone with a lot of experience in this (I plan to write more when I get to 69 posts on the front page of hacker news, I'm only at 55 right now), about half of it is that you have to be personally jazzed about the post. If you're not, it'll show and the audience here will eat you alive and either flag you or mock you. You gotta sink or swim.
BeFlatXIII
You gave a strong example of the stick figures working better than generic AI art. Ironically, the AI image was necessary to drive home the point. That AI stock “photo” is just plain boring, even in contrast to stick figures on a plain white background. Those two images are worth an infinity of words that most anti-AI art people would rant about human creativity or whatever.
AlienRobot
>Even a terrible MS Paint drawing is more interesting than an AI-generated image
True and factual. I don't get why people don't just take pictures from Flickr, CC BY-SA, just post it and link the author. Having an AI-generated image in your writing makes me think the whole text is also AI-generated.
By the way, the best thing you can do for skimmers is include images, because they break the flow of text. You can also try using headings that stand out for having inverted colors for example, but people generally don't do that with markdown and generic heading CSS.
nuredini
It's interesting to see how some of the most popular blogs in https://refactoringenglish.com/tools/hn-popularity do the opposite of what's being suggested here.
Still, for most people who are still finding their style and (for some reason) are optimizing for popularity, this seems like sound advice.
mtlynch
Thanks for reading!
I think most of the top authors on the list actually do align with the techniques I mention here.
Paul Graham doesn't, I agree. But a lot of the rest do.
Krebs, Julia Evans, Dan Luu, John Gruber, and Simon Willison all get to the point quickly and write for broad audiences. Dan Luu and John Gruber don't use a ton of images or headings, but Krebs, Evans, and Willison do.
commandersaki
Ironically I skimmed the first few paragraphs and the essence to attracting attention is to "get to the point". At which point I scrolled down to the bottom just reading the headlines and just couldn't be arsed. I'm usually more interested in the comments.
Edit: looks like I'm not alone.
testycool
I also just pre-ordered Refactoring English.
I loved your course from a few years ago - "Hit the Front Page of Hacker News".
The biggest takeaways from that course were to write for beginners, and assume no prior knowledge/context.
I've often been fascinated by articles featured on HN, that were totally out of my field, but somehow didn't make me feel stupid.
A few concepts from your course gave me some very refreshing "aha!" moments. Since then I'm almost never staring at a blank page.
Thanks so much, and looking forward to the book!
mtlynch
Thanks so much for reading and the kind words! I'm really glad to hear you've found the previous course valuable!
My general takes (as someone who also has a somewhat popular blog) is that
The inverted pyramid is almost always the correct format for your text. I often put the tweet-length version of the post in the title or first paragraph. Get to the point quickly, then elaborate. Means you can bail out at any point of the text and still take home most of what mattered, while the meticulous crowd can have their nitpicks addressed toward the end.
The problem of finding an audience is best solved by being really transparent about what you're about. Inverted pyramid solves that. There's no point to drawing in people who aren't going to be interested. Retaining existing readers beats capturing new readers.
I'm less bullish on images, unless they are profoundly relevant to the text. Illustrations for the sake of having illustrations are no bueno in my opinion. You want to reduce distractions and visual noise. Images should above all never be funny.