Hacker News

How to write blog posts that developers read

2025-03-2811:01603154refactoringenglish.com

Software bloggers can make the same mistakes for years that prevent readers from discovering their writing. I know because I'm one of them. Over time, I've learned techniques that help some blog posts…

by Michael Lynch, published

I recently spoke to a developer who tried blogging but gave up because nobody was reading his posts. I checked out his blog, and it was immediately obvious why he didn’t have any readers.

The developer had interesting insights, but he made so many mistakes in presenting his ideas that he was driving everyone away. The tragedy was that these errors were easy to fix. Once you learn to recognize them, they feel obvious, but some bloggers make these mistakes for years.

I know because I’m one of them.

I’ve been blogging about software development for nine years. My best posts have reached 300k+ readers, but many of them flopped, especially in my first few years.

Over time, I’ve learned techniques that help some blog posts succeed and the pitfalls that cause others to languish in obscurity.

Why listen to me?🔗

I’m going to say a bunch of gloaty things to establish credibility, but it feels gross, so let’s just get it out of the way:

  • I’ve written a software blog for nine years, and it attracts 300k-500k unique readers per year.
  • My posts have reached the front page of Hacker News over 30 times, many of them reaching the #1 spot.
  • I launched a successful indie business by writing a popular blog post about my product.
  • My articles frequently appear on reddit and Lobsters.

Even a terrible MS Paint drawing is more interesting than an AI-generated image.

Many readers skim an article first to decide if it’s worth reading. Dazzle those readers during the skim.

If the reader only saw your headings and images, would it pique their interest?

The worst thing for a skimmer to see is a wall of text: long paragraphs with no images or headings to break them up. Just text, text, text all the way down.

Tool: Read like a skimmer🔗

Here’s a JavaScript bookmarklet that you can use to see what your article looks like with just headings and images.

Drag the link to your browser bookmark bar, and then click it to see what your article looks like to skimmers.

Example: Boring structure vs. interesting structure🔗

I wrote my article, “End-to-End Testing Web Apps: The Painless Way,” in 2019, before I thought about structure.

If you skim the article, does it make you want to read the full version?

Probably not. The headings don’t reveal much about the content, and the visuals are confusing.

Consider my more recent article, “I Regret My $46k Website Redesign.”

If you skim that article, you still see the bones of a good story, and there are interesting visual elements to draw the reader in.

One of those articles barely attracted any readers, and the other became one of the most popular articles I ever published, attracting 150k unique readers in its first week. Can you guess which is which?

In the nine years I've been blogging about software development, some of my posts have hit 300k+ readers, while others flopped, especially early on. I'm sharing all the lessons I learned the hard way about how to write popular blog posts for developers. refactoringenglish.com/chapters/wri...

[image or embed]


Read the original article

rbanffy

Karma: 186817
...
 @Hacker__News
@hacker._news

Comments

  • By marginalia_nu 2025-03-2814:0115 reply

    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.

    • By hk1337 2025-03-2819:005 reply

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

      • By ZYbCRq22HbJ2y7 2025-03-291:51

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

      • By ghaff 2025-03-2821:321 reply

        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.

        • By eichin 2025-03-291:061 reply

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

          • By ghaff 2025-03-296:12

            Yeah. I was on a student paper and then actually co-founded one at a different school. At the time I don’t we used wire service copy in either case but you still needed to make stuff fit.

      • By strogonoff 2025-03-2912:32

        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.

      • By forrestthewoods 2025-03-2821:384 reply

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

        • By chatmasta 2025-03-291:141 reply

          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?

          • By grandempire 2025-03-296:02

            > Whereas in the real world, you are competing for attention, and nobody has to read what you write

            Note that this is a cultural artifact relative to our time where marketing and lobbying are so pervasive. Aristotle isn’t written to grab your attention.

        • By tehjoker 2025-03-2822:042 reply

          The articles were intended for you to read. If you find them annoying, maybe they weren't written for you.

          • By MonkeyClub 2025-03-2822:111 reply

            > The articles were intended for you to read

            Or they were intended for you to scroll further on the page and load more ads and autoplay videos.

            Good essays start with their thesis, expand upon that, and conclude by bringing it back to it.

            There is no reason journalism should veer away from a format that works for one goal (information dissemination), unless there are other goals at play (longer engagement).

            • By tehjoker 2025-03-2822:131 reply

              Perhaps novels should be written in the inverted triangle format.

              • By jkmcf 2025-03-2822:391 reply

                Perhaps there's a difference between fiction and non-fiction

                • By tehjoker 2025-03-291:551 reply

                  I think the author can decide how they wish to present their work

                  • By MonkeyClub 2025-03-2914:06

                    But the author has no intent!

                    (Eng. Lit. /s)

          • By forrestthewoods 2025-03-294:57

            There are more long form articles available than I have time to read. I hate when a juicy sounding headline grabs my attention, but I have to read for 5 minutes just to figure out what it’s actually about and if I want to keep reading. The disappointment of going from “interesting title” to “vague unimportant flashback” is immense.

        • By ako 2025-03-296:29

          I feel like most news articles I read miss the why, just like your first sentence.

        • By miki123211 2025-03-2822:04

          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

      • By jvanderbot 2025-03-2914:391 reply

        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?

        • By ithkuil 2025-03-2921:521 reply

          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)

          • By jvanderbot 2025-03-2923:35

            So it's precisely the opposite. Wonderful. I suppose I shouldn't expect anything different, after a few decades of seeing these opposite interpretations arise in parallel.

    • By pansa2 2025-03-2816:365 reply

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

      • By kqr 2025-03-2818:51

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

      • By ketzo 2025-03-295:11

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

      • By marginalia_nu 2025-03-2818:04

        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.

      • By RicoElectrico 2025-03-2820:14

        Good story defends itself even if you know the ending.

      • By sunshowers 2025-03-2817:46

        There's a tension here but I don't think it's a fundamental conflict.

    • By ddejohn 2025-03-2819:104 reply

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

      • By dwedge 2025-03-2822:30

        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.

      • By marginalia_nu 2025-03-2819:372 reply

        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.

        • By wavemode 2025-03-290:46

          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.

        • By mtlynch 2025-03-2820:31

          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.

      • By roland35 2025-03-2912:57

        I think the key is to be your authentic self. If you’re trying to force being funny it comes off poorly.

      • By greenchair 2025-03-2820:57

        it decreases authority projection

    • By rsync 2025-03-2817:041 reply

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

      • By Noumenon72 2025-03-292:451 reply

        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.

    • By sunk1st 2025-03-2814:045 reply

      Wouldn’t that be a regular pyramid? In what sense is it inverted?

      • By tantalor 2025-03-2814:391 reply

        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"

        • By irrational 2025-03-2818:16

          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.

      • By kens 2025-03-2817:19

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

      • By Galanwe 2025-03-2814:09

        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.

      • By jasode 2025-03-2814:141 reply

        > In what sense is it inverted?

        The triangle is upside down:

        https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)

        • By azornathogron 2025-03-2814:333 reply

          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.

          • By wonger_ 2025-03-2814:47

            I think it's about laying foundations at the beginning, not the length of the text at the beginning. The first sentence/paragraph is the foundation of everything beneath it, whereas the base of a normal pyramid is the foundation of everything above it.

          • By kqr 2025-03-2818:58

            > I really don't see any particular relationship between the shape and its content.

            This is often the case with geometric metaphors. They catch on easily, but they rarely make a lot of sense on closer scrutiny.

          • By marginalia_nu 2025-03-2814:35

            Yeah, this seems to be true for most pyramid models. It's really annoying when you start to spot it.

      • By marginalia_nu 2025-03-2814:12

        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.

    • By mvkel 2025-03-2814:433 reply

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

      • By yesfitz 2025-03-2815:222 reply

        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.

        • By PeterFBell 2025-03-2816:551 reply

          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 :)

          • By mvkel 2025-03-2916:07

            This sounds like a business book on cats. Useful, yes, but not something I'd read for its writing value.

        • By mvkel 2025-03-2916:06

          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

      • By xmprt 2025-03-2817:02

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

      • By rzzzt 2025-03-2819:00

        It doesn't work for me, I get a little angry each time I read the above-the-fold five word hot take.

    • By mtlynch 2025-03-2814:162 reply

      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.

      • By marginalia_nu 2025-03-2814:243 reply

        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.

        • By lapcat 2025-03-2814:301 reply

          > Mixing humor into serious communication comes at the expense of authenticity.

          Only if you're authentically humorless. ;-)

          • By marginalia_nu 2025-03-2814:341 reply

            I wouldn't say never under any circumstance to do this, a pun or a joke occasionally creeps into my posts as well, though I feel this is definitely a less-is-more thing.

            You sometimes find texts where you get the feeling the author almost expects a sitcom laugh track over the post, and funnies are crammed into every available crevice.

            • By lapcat 2025-03-2814:57

              To put it in perspective, I would note that the article title specifies "how to write blog posts", plural, not merely "how to write a blog post", singular. In other words, you're promoting a body of work, or for lack a better term, a "brand". If you want your brand to be authentic, it needs to reflect your personality. Thus, I think there is leeway for humor, even sarcasm, meandering, rambling, if that's what you tend to do. If you can establish a brand, an audience, then readers will stay with your blog posts because they were written by you, in spite of your style, or perhaps due to your style. Ultimately, of course, you need something interesting and/or important to say, but you don't need to present it robotically. Unless you are a robot! The negative oneth law of robotics is that a robot must not attempt humor.

        • By n0tquitehere 2025-03-297:28

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

          * https://www.humorseriously.com/

        • By ThrowawayR2 2025-03-2914:48

          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 .

      • By bookofjoe 2025-03-2814:411 reply

        For sure a HN comment should never have jokes: instant downvotes. Watch this space...

        • By mtlynch 2025-03-2816:462 reply

          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.

          • By dalmo3 2025-03-2820:40

            The HN version of that is that the top comment is often an analogy and then a massive thread of people just talking about the analogy rather than the actual point.

          • By marginalia_nu 2025-03-2819:281 reply

            I think HN can be quite forgiving when it comes to jokes, as long as they are genuinely funny and fresh. What doesn't go well is predictable reference humor and tired old memes.

            • By bookofjoe 2025-03-2913:37

              Unfortunately for me, that's all I got. No quarter for being a geezer (76).

    • By SwtCyber 2025-03-297:20

      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.

    • By mousetree 2025-03-2818:182 reply

      When I worked in consulting, we would call this “top down communication” - starting with the key message first. As opposed to storytelling.

      • By airstrike 2025-03-2818:54

        I've heard it called BLUF, from the military, apparently. Bottom line up front.

      • By kqr 2025-03-2818:59

        I believe some domains use BLUF, for bottom line up front.

    • By barbazoo 2025-03-2814:521 reply

      I really like that concept and I’ve never heard of it. Makes me want to pay attention if people do that outside of tech.

      > Images should above all never be funny

      :)

      • By ramon156 2025-03-2815:50

        I think a better term is "witty". For example, fasterthanlime's blog executes the funny part well, but it never tries to be witty.

    • By gusmally 2025-03-2815:561 reply

      • By kens 2025-03-2816:58

        Barbara Minto's Pyramid Principle is different. She invented that in 1985. The journalism "inverted pyramid" is much older, going back to the 1800s.

    • By jvanderbot 2025-03-2913:57

      You just described pyramid (point at top) but called it inverted pyramid (point at bottom)

    • By 0cf8612b2e1e 2025-03-2815:071 reply

      Also known as BLUF: bottom line up front.

    • By pipes 2025-03-2911:41

      The reverse of a wired article then. Takes about ten pages of scrolling to to get to the point.

    • By b0rsuk 2025-03-2916:20

      [dead]

  • By stephantul 2025-03-2818:083 reply

    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.

    • By mtlynch 2025-03-2818:382 reply

      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.

      • By tasuki 2025-03-2821:091 reply

        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.

        • By mtlynch 2025-03-2821:20

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

          [0] https://refactoringenglish.com/chapters/

      • By stephantul 2025-03-2819:591 reply

        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.

        • By mtlynch 2025-03-2820:21

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

    • By Retr0id 2025-03-292:48

      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.

    • By SwtCyber 2025-03-297:22

      I think, writing for yourself first, without worrying about views or rankings, is where a lot of the real value comes from

  • By dynm 2025-03-2815:504 reply

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

    • By kqr 2025-03-2819:022 reply

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

      • By bluGill 2025-03-2820:07

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

      • By mtlynch 2025-03-2819:37

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

    • By rikroots 2025-03-2817:58

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

    • By SwtCyber 2025-03-297:26

      I really like the "write something you'd actually read" rule

    • By swyx 2025-03-2816:49

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

HackerNews

About