[HN Gopher] How to write blog posts that developers read
___________________________________________________________________
How to write blog posts that developers read
Author : rbanffy
Score : 272 points
Date : 2025-03-28 11:01 UTC (11 hours ago)
(HTM) web link (refactoringenglish.com)
(TXT) w3m dump (refactoringenglish.com)
| mtlynch wrote:
| Author here.
|
| I'm happy to take any feedback or answer any questions about this
| post.
| jppope wrote:
| Thank you for building the personal blog ranking btw.
|
| If I remember correctly you sold your hardware business
| recently (or it felt recently). I'm curious, what is the
| motivation for moving into the content business? I'm certainly
| interested in this project, and will likely buy the book, etc,
| but I'm also somewhat disappointed to not see you going after
| something bigger/harder/technical and sharing that journey. I
| found your previous work very inspiring.
|
| I don't want to insinuate that I don't think this is valuable,
| it definitely is, and I expect it to be successful. I'm just
| curious about what led you from point A to point B on this one.
| mtlynch wrote:
| Thanks for reading!
|
| > _I 'm curious, what is the motivation for moving into the
| content business? I'm certainly interested in this project,
| and will likely buy the book, etc, but I'm also somewhat
| disappointed to not see you going after something
| bigger/harder/technical and sharing that journey. I found
| your previous work very inspiring._
|
| I'm trying to find a business that lets me write about
| technical things that I find interesting and have it be
| financially viable and aligned with my readers' interests.
|
| When I was running TinyPilot, I wanted to write about a lot
| of what I was doing, but the pace of the business was tough,
| so I had very little time to write. And after the first few
| months, my writing didn't have a measureable impact on the
| business anymore. I liked to think that it did, but it was
| hard to allocate so much of my time to blogging when I could
| have been working on other parts of the business.
|
| And it makes sense that blogging wouldn't help TinyPilot
| much. I think there's overlap between people who read my blog
| and people who are interested in that product, but it's not
| super aligned. Like the people interested in running an indie
| business are not necessarily interested in buying a KVM over
| IP device.
|
| There are a few different models for making money from
| blogging (ads, affiliate deals, paid membership). The one
| that appeals to me most is what Julia Evans[0] does, where
| she blogs about what she's interested in, but she has paid
| products[1] that allow readers to contribute back
| financially.
|
| I'd eventually like to get back to a SaaS or some type of
| software product, but I'd like to see if I can make the book
| work, as there's a lot I'd like to teach that I don't see
| elsewhere.
|
| But in general, I think educational products ("info
| products") have an unfortunate stigma. I've only done one,
| but I found it to be a great way to learn about indie
| businesses because it's a microcosm of the whole process of
| customer discovery, marketing, and sales. But it has the
| advantage of not being a long-term promise, so if it doesn't
| work out, you just move on to the next thing rather than tell
| all of the early customers who bet on you that you're
| shutting down and killing off their product.
|
| [0] https://jvns.ca
|
| [1] https://wizardzines.com/
| eimrine wrote:
| How much of a cyanacrylat glue have you spent for making that
| photo with stones? I am not sure whether the top stone is image
| collage but I can promise the bottom 3 stones of 4 is a real
| picture ^_^
| mtlynch wrote:
| Haha, none personally but maybe the photographer did. It's a
| free stock photo.[0]
|
| I hired an illustrator to design a custom cover for me, but
| the project went off the rails, as the artist was using AI in
| ways I disliked, so I ended up just doing my own mediocre
| cover in two hours.[1]
|
| [0] https://unsplash.com/photos/shallow-focus-photo-gray-
| balance...
|
| [1] https://mtlynch.io/retrospectives/2025/01/#my-poor-
| experienc...
| paulluuk wrote:
| Tiny nitpick: instead of using the nested circle diagram, I
| feel like a venn diagram would be more accurate. I don't think
| that all developers are blog readers.
| marginalia_nu wrote:
| 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.
| sunk1st wrote:
| Wouldn't that be a regular pyramid? In what sense is it
| inverted?
| Galanwe wrote:
| 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.
| marginalia_nu wrote:
| 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.
| jasode wrote:
| _> In what sense is it inverted?_
|
| The triangle is upside down:
|
| https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)
| azornathogron wrote:
| 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 wrote:
| Yeah, this seems to be true for most pyramid models. It's
| really annoying when you start to spot it.
| wonger_ wrote:
| 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.
| kqr wrote:
| > 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.
| tantalor wrote:
| 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 wrote:
| 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 wrote:
| 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=%.
| ..
| mtlynch wrote:
| 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 wrote:
| 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 wrote:
| > Mixing humor into serious communication comes at the
| expense of authenticity.
|
| Only if you're authentically humorless. ;-)
| marginalia_nu wrote:
| 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.
| lapcat wrote:
| 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.
| bookofjoe wrote:
| For sure a HN comment should never have jokes: instant
| downvotes. Watch this space...
| mtlynch wrote:
| 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.
| marginalia_nu wrote:
| 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.
| dalmo3 wrote:
| 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.
| mvkel wrote:
| 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 wrote:
| 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 wrote:
| 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 :)
| xmprt wrote:
| 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 wrote:
| It doesn't work for me, I get a little angry each time I read
| the above-the-fold five word hot take.
| barbazoo wrote:
| 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
|
| :)
| ramon156 wrote:
| I think a better term is "witty". For example,
| fasterthanlime's blog executes the funny part well, but it
| never tries to be witty.
| 0cf8612b2e1e wrote:
| Also known as BLUF: bottom line up front.
| teddyh wrote:
| <https://en.wikipedia.org/w/index.php?title=BLUF_(communicati
| ...>
| gusmally wrote:
| aka Barbara Minto's Pyramid Principle:
| https://www.mckinsey.com/alumni/news-and-events/global-news/...
| kens wrote:
| Barbara Minto's Pyramid Principle is different. She invented
| that in 1985. The journalism "inverted pyramid" is much
| older, going back to the 1800s.
| pansa2 wrote:
| > 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?
| sunshowers wrote:
| There's a tension here but I don't think it's a fundamental
| conflict.
| marginalia_nu wrote:
| 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.
| kqr wrote:
| 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...
| RicoElectrico wrote:
| Good story defends itself even if you know the ending.
| rsync wrote:
| "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.
| mousetree wrote:
| When I worked in consulting, we would call this "top down
| communication" - starting with the key message first. As
| opposed to storytelling.
| airstrike wrote:
| I've heard it called BLUF, from the military, apparently.
| Bottom line up front.
| kqr wrote:
| I believe some domains use BLUF, for bottom line up front.
| hk1337 wrote:
| > 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.
| ghaff wrote:
| 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.
| forrestthewoods wrote:
| > 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.
| miki123211 wrote:
| 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
| tehjoker wrote:
| The articles were intended for you to read. If you find
| them annoying, maybe they weren't written for you.
| MonkeyClub wrote:
| > 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).
| tehjoker wrote:
| Perhaps novels should be written in the inverted triangle
| format.
| jkmcf wrote:
| Perhaps there's a difference between fiction and non-
| fiction
| ddejohn wrote:
| > 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.
| marginalia_nu wrote:
| 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.
| mtlynch wrote:
| 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.
| greenchair wrote:
| it decreases authority projection
| dwedge wrote:
| 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.
| barbazoo wrote:
| I thought this was going to be a prompt engineering SaaS to
| rewrite people's technical blog posts. Glad it wasn't.
| MartijnHols wrote:
| 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.
| mtlynch wrote:
| > _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.
| kristopolous wrote:
| 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 wrote:
| > 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.
| swyx wrote:
| 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"
|
| ex: https://www.swyx.io/bottom-up-ideas
| CuriouslyC wrote:
| 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 wrote:
| 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.
| jdeanwallace wrote:
| Pre-ordered!
| mtlynch wrote:
| Thanks Jason! But haven't I pestered you about passive voice
| enough? You still want more? : )
| diogolsq wrote:
| In your first phrases you should already made your context,
| intent and Key message clear.(Framing)
|
| this is one of the lessons of The first minute, a short book that
| goes well with this blog post.
| dynm wrote:
| 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...
| swyx wrote:
| > "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
| rikroots wrote:
| > 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.
| kqr wrote:
| > 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.
| mtlynch wrote:
| > _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.
| bluGill wrote:
| 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..)
| aizk wrote:
| Promise progress payoff. Give users a promise about what you're
| going to show them, make constant progress, and have a nice
| payoff at the end. Brandon Sanderson talks about it in his
| lecture series on youtube.
| swyx wrote:
| just my little contribution as a somewhat known writer: make your
| titles count https://dx.tips/titles
| testycool wrote:
| 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 wrote:
| Thanks so much for reading and the kind words! I'm really glad
| to hear you've found the previous course valuable!
| norir wrote:
| This advice strikes me as very sensible if I want to maximize my
| audience of readers who lack the attention span to take in any
| information of real depth.
| AmazingTurtle wrote:
| 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 wrote:
| 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 wrote:
| > 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.
| tzcnt wrote:
| Honestly, thanks... I'm about to start my first foray into blog-
| post writing, and I have a couple specific topics in mind. I had
| been debating whether I should start with the "background and
| motivation" section, or if I should just get to the point. Your
| article helped me decide that I should definitely just get to the
| point first. If the reader cares to go deeper into my specific
| motivation, then they can. But at the end of the day, the purpose
| of my post is to share knowledge - and soapboxing should be
| secondary.
| mtlynch wrote:
| Thanks, I'm glad you enjoyed it!
|
| My advice for just starting out is to not worry too much about
| following all the right practices. The more important thing is
| to try the process start to finish of picking a topic, writing
| a draft, editing it, publishing it, and finding places to share
| it. I'd start with something narrowly scoped that you can
| explain in 2,000 words or less.
|
| I suspect that just experiencing the process end-to-end will
| give you a better sense of what areas you struggle with, and it
| will help you prioritize what writing advice to seek out.
| avinassh wrote:
| on this similar topic, the book `Writing for Developers - Blogs
| that get read` is also a great book
| cyndunlop wrote:
| Details:
| https://github.com/scynthiadunlop/WritingForDevelopersBook
| stephantul wrote:
| 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 wrote:
| 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.
| stephantul wrote:
| 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 wrote:
| > _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.
| tasuki wrote:
| 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 wrote:
| > _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/
| remoquete wrote:
| The most interesting content I found through HN had no pictures
| or illustrations.
| ezekg wrote:
| > Accommodate skimmers. 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.
|
| It's funny because I've found that my posts do better on HN
| without any headings (though I do use shorter paragraphs for the
| no-headers).
|
| p.s. almost all of my front-page posts were no-headers!
| mtlynch wrote:
| > _almost all of my front-page posts were no-headers!_
|
| Those posts would all still be on the front page today if they
| had included headings!
|
| But really, I admit that this is my most subjective point. I
| feel like headings are helpful, but a lot of the writers I
| admire don't use them (Paul Graham, Joel Spolsky, DHH).
| janalsncm wrote:
| A meta question one should ask is: why do you want to write a
| technical blog in the first place? If it is fame and fortune,
| blogging about your favorite obscure technology probably isn't
| the easiest path.
|
| On the other hand, if it is for the purpose of your own
| understanding, then it doesn't matter whether you have enough
| pictures, or your first paragraph elicits sufficient dopamine to
| compete with TikTok. By default the most important audience will
| be yourself in the future, and by definition if you're rereading
| the article you're already interested. Instead, you should focus
| on highly detailed and precise language which help you understand
| the topic in the future.
|
| Likewise, if it is for the purpose of bolstering your
| professional profile, it's unlikely your content will be
| evaluated on how catchy it is.
| AlienRobot wrote:
| >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.
| tehjoker wrote:
| One strategy that wasn't mentioned: submit your work to a
| magazine. Distribution is everything. It is very difficult to
| self-promote.
___________________________________________________________________
(page generated 2025-03-28 23:00 UTC)