7 ms·
How to write blog posts that developers read
- deleted 2y ago[deleted]
- rbrownrw8 2y agoSo should you always err on the side of shorter blog posts? Is a long-winded blog post ever necessary?
- mtlynch 2y agoAuthor here. I'm happy to take any feedback or answer any questions about this post.
- jppope 2y agoThank 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 2y agoThanks 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 https://jvns.ca [1] https://wizardzines.com/ https://wizardzines.com/
- eimrine 2y agoHow 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 2y agoHaha, 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-stone-HWRAHxoBlpU https://unsplash.com/photos/shallow-focus-photo-gray-balance... [1] https://mtlynch.io/retrospectives/2025/01/#my-poor-experience-hiring-a-book-cover-designer-through-reedsy https://mtlynch.io/retrospectives/2025/01/#my-poor-experienc...
- paulluuk 2y agoTiny 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.
- mtlynch 2y agoYeah, that's true. I considered a Venn diagram, but I feel like those convey that the emphasis is on the overlap, whereas I actually just want concentric circles. I think the issue is more the top-level category. I should change it to something that strictly contains "Programmers."
- marginalia_nu 2y agoMy 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 2y agoWouldn’t that be a regular pyramid? In what sense is it inverted?
- Galanwe 2y agoThat 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 2y agoIt'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 2y ago> In what sense is it inverted? The triangle is upside down: https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism) https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)
- barbazoo 2y agoI thought this was going to be a prompt engineering SaaS to rewrite people’s technical blog posts. Glad it wasn’t.
- MartijnHols 2y agoSo 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 2y ago>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 2y agoI 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 2y ago
- jdeanwallace 2y agoPre-ordered!
- mtlynch 2y agoThanks Jason! But haven't I pestered you about passive voice enough? You still want more? : )
- diogolsq 2y agoIn 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 2y agoI 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-developers-read/#you-need-a-realistic-path-to-your-readers https://refactoringenglish.com/chapters/write-blog-posts-dev...
- swyx 2y ago> "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 2y ago> 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 2y ago> 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.
- aizk 2y agoPromise 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 2y agojust my little contribution as a somewhat known writer: make your titles count https://dx.tips/titles https://dx.tips/titles
- testycool 2y agoI 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 2y agoThanks so much for reading and the kind words! I'm really glad to hear you've found the previous course valuable!
- norir 2y agoThis 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 2y agoIronically 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 2y agoAuthor 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 2y ago> 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 2y agoSample 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.
- tzcnt 2y agoHonestly, 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 2y agoThanks, 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 2y agoon this similar topic, the book `Writing for Developers - Blogs that get read` is also a great book
- cyndunlop 2y agoDetails: https://github.com/scynthiadunlop/WritingForDevelopersBook https://github.com/scynthiadunlop/WritingForDevelopersBook
- stephantul 2y agoCounterpoint: 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 2y agoAuthor 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 2y agoThanks 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.
- remoquete 2y agoThe most interesting content I found through HN had no pictures or illustrations.
- ezekg 2y ago> 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 2y ago>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 2y agoA 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 2y ago>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 2y agoOne strategy that wasn't mentioned: submit your work to a magazine. Distribution is everything. It is very difficult to self-promote.
- max_ 2y agoAny good magazines you recommend?
- xena 2y agoTBH 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.
- alanh 2y agoI recently opined here that devs should really stop setting their blogs in monospaced fonts, and got downvoted to -4, which is very funny. It’s TRUE! Monospaced fonts are a thing for two reasons: 1. Historically, they were all computers did, because it is simpler to have fixed widths. (Remember Knuth's biggest contribution was typesetting -- it is complex). Do you know why the Macintosh changed this? Because Jobs was inspired by a calligraphy course he audited at college 2. Because lining up text is important for programming Other than that, variable-width text is much easier to scan and read. Yes, even for people who spend a lot of time working with code. You should also be setting a maximum line-width of about 40em, as it becomes hard to read text when the eye has so far to travel back to the left side. You also shouldn't center paragraphs 99% of the time, because it’s better when your eye can 'seek' to a consistent left edge (assuming LTR languages!) If you want to know more, please look it up or ask the nearest LLM!
- BeFlatXIII 2y agoYou 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.
- nextts 2y agoParallels with Amy Hoy's "eBombs"
- rednafi 2y agoSteve 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/ https://rednafi.com/
- sepositus 2y ago> It reached the front page of Hacker News, even though readers there are generally hostile to cryptocurrency-focused stories. The real litmus test :)
- sagarpatil 2y agoI agree with the author. What’s recently worked for me is to ask the AI to critique my blog/hn/reddit posts and ask it to be brutally honest. The feedback that I got from it was eye opening and I used to write exactly like the author mentioned: a lot of meandering.
- deleted 2y ago[deleted]
- kazinator 2y ago> Except that can’t happen because there are so many Python tutorials out there already on sites that Google prefers over yours. You could always pay Google.
- SwtCyber 2y agoAppreciated the reminder to show, not tell with images and structure. Most dev blogs are just walls of text with the occasional code block. Adding even rough diagrams or skimmable headings makes a massive difference.
- nuredini 2y agoIt's interesting to see how some of the most popular blogs in https://refactoringenglish.com/tools/hn-popularity 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 2y agoThanks 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.
- DeathArrow 2y ago>Internet attention spans are short. This! But how to overcome it? Some times to better convey the idea you have to write a lot. Split the article in parts? Only provide a very high level overview? And how long can be a blog post or article until people start to get bored and leave?
- rocqua 2y agoStart with the overview, let people decide quickly whether this is worth investing more time in.
- yapyap 2y agoYes, but also if you are not good in writing articles don’t quit writing them, getting better in writing articles comes with.. writing articles. Also you should not necessarily optimize your blog post for the max amount of readers, that’s only useful in commercial cases or when you want to commercialize yourself.
- jimkleiber 2y agoI'm really curious how these insights might apply to other internet media (mediums?). Similar principles at play for YouTube videos? Audio-only podcasts? I'm only halfway through the post but really excited to think of how this might extrapolate to other formats.
- commandersaki 2y agoIronically 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.
- adadfg 2y ago[dead]
- adadfg 2y ago[dead]