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.
> 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.
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.
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.
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...
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.
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.
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?
> 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.
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).
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.
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?
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)
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.
> 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?
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!”
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.
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.
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.
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.
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.
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.
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.
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.
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"
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.
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.
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.
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.
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.
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 :)
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
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).
>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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
>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.
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.
>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]
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.
>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.
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.)
> 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.
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..)
>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.
> 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.
Steve Ballmer never diversified his Microsoft stock like Bill Gates did. But it made him an immensely rich guy—currently richer than Gates himself. Now, does that mean picking a company and going all in is a good idea? Probably not.
I’m all about improving my writing to be useful to others. However, diversifying my content to attract a broader audience usually results in the most vapid, formulaic, clickbaity articles. No matter how many eyeballs they get, I don’t get any pleasure reading or writing them. And writing is how I slow down and shape my thinking. I like doing it for myself, not for the audience. But I deeply appreciate however many readers I get.
Hacker News has a pattern of articles it favors: Zig, Rust, why Go isn’t for the “smart” developers, arcane PL theories, nostalgia about some Lisp variant, why you should blog, small internet, and so on. Ninety percent of the time, they’re forgettable. I usually learn more from the comments than the articles themselves. I also don’t want to write just to capture a certain kind of audience.
I mostly write about things I’m currently working with or interested in. I tend to write something I think past me would find useful—and future me might, too. That’s very different from shaping your writeups for the audience. My stats aren’t impressive as the author, but I do get a few thousand monthly visitors to my blog[1]. I’ve had job offers because a recruiter came across one of my posts somewhere. It’s a different way of thinking about writing, but I’m immensely happy with the result.
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.
> 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.
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.
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.
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.
> 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.
>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.
TBH as someone with a lot of experience in this (I plan to write more when I get to 69 posts on the front page of hacker news, I'm only at 55 right now), about half of it is that you have to be personally jazzed about the post. If you're not, it'll show and the audience here will eat you alive and either flag you or mock you. You gotta sink or swim.
You gave a strong example of the stick figures working better than generic AI art. Ironically, the AI image was necessary to drive home the point. That AI stock “photo” is just plain boring, even in contrast to stick figures on a plain white background. Those two images are worth an infinity of words that most anti-AI art people would rant about human creativity or whatever.
>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.
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.
Appreciated 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.
Ironically I skimmed the first few paragraphs and the essence to attracting attention is to "get to the point". At which point I scrolled down to the bottom just reading the headlines and just couldn't be arsed. I'm usually more interested in the comments.
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.
>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.
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 ^_^
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]
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.
Yeah, 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."
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.
> 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!
>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).
Yes, 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.
I'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.
I 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.
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.
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.
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.
I 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!
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.
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.
> 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.
> 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.
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.
> 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...
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.
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.
> 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.
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?
> 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.
The articles were intended for you to read. If you find them annoying, maybe they weren't written for you.
> 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).
Perhaps novels should be written in the inverted triangle format.
Perhaps there's a difference between fiction and non-fiction
I think the author can decide how they wish to present their work
But the author has no intent!
(Eng. Lit. /s)
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.
I feel like most news articles I read miss the why, just like your first sentence.
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
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?
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)
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.
> 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?
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!”
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...
Good story defends itself even if you know the ending.
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.
There's a tension here but I don't think it's a fundamental conflict.
“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.
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.
It is exactly what you expected - click the "body" link and you'll see the entire topic fully expanded:
https://john.kozubik.com/pub/IcebergArticle/body.html
A few years ago I wrote an implementation of what you describe: https://skorokithakis.github.io/expounder/
> 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.
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.
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.
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.
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.
I think the key is to be your authentic self. If you’re trying to force being funny it comes off poorly.
it decreases authority projection
Wouldn’t that be a regular pyramid? In what sense is it inverted?
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"
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.
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=%...
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.
> In what sense is it inverted?
The triangle is upside down:
https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)
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.
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.
> 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.
Yeah, this seems to be true for most pyramid models. It's really annoying when you start to spot it.
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.
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:"
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.
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 :)
This sounds like a business book on cats. Useful, yes, but not something I'd read for its writing value.
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
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).
It doesn't work for me, I get a little angry each time I read the above-the-fold five word hot take.
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.
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.
> Mixing humor into serious communication comes at the expense of authenticity.
Only if you're authentically humorless. ;-)
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.
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.
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/
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 .
For sure a HN comment should never have jokes: instant downvotes. Watch this space...
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.
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.
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.
Unfortunately for me, that's all I got. No quarter for being a geezer (76).
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.
When I worked in consulting, we would call this “top down communication” - starting with the key message first. As opposed to storytelling.
I've heard it called BLUF, from the military, apparently. Bottom line up front.
I believe some domains use BLUF, for bottom line up front.
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
:)
I think a better term is "witty". For example, fasterthanlime's blog executes the funny part well, but it never tries to be witty.
aka Barbara Minto's Pyramid Principle: https://www.mckinsey.com/alumni/news-and-events/global-news/...
Barbara Minto's Pyramid Principle is different. She invented that in 1985. The journalism "inverted pyramid" is much older, going back to the 1800s.
You just described pyramid (point at top) but called it inverted pyramid (point at bottom)
The reverse of a wired article then. Takes about ten pages of scrolling to to get to the point.
Also known as BLUF: bottom line up front.
<https://en.wikipedia.org/w/index.php?title=BLUF_(communicati...>
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.
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.
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.
>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/
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.
>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.
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.
I think, writing for yourself first, without worrying about views or rankings, is where a lot of the real value comes from
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...
> 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.
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..)
>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.
> 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.
I really like the "write something you'd actually read" rule
> "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
Steve Ballmer never diversified his Microsoft stock like Bill Gates did. But it made him an immensely rich guy—currently richer than Gates himself. Now, does that mean picking a company and going all in is a good idea? Probably not.
I’m all about improving my writing to be useful to others. However, diversifying my content to attract a broader audience usually results in the most vapid, formulaic, clickbaity articles. No matter how many eyeballs they get, I don’t get any pleasure reading or writing them. And writing is how I slow down and shape my thinking. I like doing it for myself, not for the audience. But I deeply appreciate however many readers I get.
Hacker News has a pattern of articles it favors: Zig, Rust, why Go isn’t for the “smart” developers, arcane PL theories, nostalgia about some Lisp variant, why you should blog, small internet, and so on. Ninety percent of the time, they’re forgettable. I usually learn more from the comments than the articles themselves. I also don’t want to write just to capture a certain kind of audience.
I mostly write about things I’m currently working with or interested in. I tend to write something I think past me would find useful—and future me might, too. That’s very different from shaping your writeups for the audience. My stats aren’t impressive as the author, but I do get a few thousand monthly visitors to my blog[1]. I’ve had job offers because a recruiter came across one of my posts somewhere. It’s a different way of thinking about writing, but I’m immensely happy with the result.
[1]: https://rednafi.com/
Any examples of this? > why Go isn’t for the “smart” developers
Lots.
https://news.ycombinator.com/item?id=37192467
https://news.ycombinator.com/item?id=9266184
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
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.
> 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.
Sample size 1. To increase to 2:
I opened it, read enough to establish this author knows what they are talking about and bookmarked it to read properly before my next blog post.
Had they told me the blogging equivalent of their intergenerational nanna's spaghetti recipe first I may not have done that.
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.
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.
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.
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.
> 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.
>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.
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
TBH as someone with a lot of experience in this (I plan to write more when I get to 69 posts on the front page of hacker news, I'm only at 55 right now), about half of it is that you have to be personally jazzed about the post. If you're not, it'll show and the audience here will eat you alive and either flag you or mock you. You gotta sink or swim.
You gave a strong example of the stick figures working better than generic AI art. Ironically, the AI image was necessary to drive home the point. That AI stock “photo” is just plain boring, even in contrast to stick figures on a plain white background. Those two images are worth an infinity of words that most anti-AI art people would rant about human creativity or whatever.
>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.
It's interesting to see how some of the most popular blogs in https://refactoringenglish.com/tools/hn-popularity do the opposite of what's being suggested here.
Still, for most people who are still finding their style and (for some reason) are optimizing for popularity, this seems like sound advice.
Thanks for reading!
I think most of the top authors on the list actually do align with the techniques I mention here.
Paul Graham doesn't, I agree. But a lot of the rest do.
Krebs, Julia Evans, Dan Luu, John Gruber, and Simon Willison all get to the point quickly and write for broad audiences. Dan Luu and John Gruber don't use a ton of images or headings, but Krebs, Evans, and Willison do.
Appreciated 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.
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!
Thanks so much for reading and the kind words! I'm really glad to hear you've found the previous course valuable!
Ironically I skimmed the first few paragraphs and the essence to attracting attention is to "get to the point". At which point I scrolled down to the bottom just reading the headlines and just couldn't be arsed. I'm usually more interested in the comments.
Edit: looks like I'm not alone.
Author here.
I'm happy to take any feedback or answer any questions about this post.
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.
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/
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 ^_^
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...
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.
Yeah, 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."
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.
> 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!
>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).
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.
Yes, 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.
I'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.
I 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.
So should you always err on the side of shorter blog posts? Is a long-winded blog post ever necessary?
I thought this was going to be a prompt engineering SaaS to rewrite people’s technical blog posts. Glad it wasn’t.
>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?
Start with the overview, let people decide quickly whether this is worth investing more time in.
The most interesting content I found through HN had no pictures or illustrations.
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.
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.
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.
I 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!
> 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.
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.
> It reached the front page of Hacker News, even though readers there are generally hostile to cryptocurrency-focused stories.
The real litmus test :)
One strategy that wasn't mentioned: submit your work to a magazine. Distribution is everything. It is very difficult to self-promote.
Any good magazines you recommend?
on this similar topic, the book `Writing for Developers - Blogs that get read` is also a great book
Details: https://github.com/scynthiadunlop/WritingForDevelopersBook
just my little contribution as a somewhat known writer: make your titles count https://dx.tips/titles
Parallels with Amy Hoy's "eBombs"
Pre-ordered!
Thanks Jason! But haven't I pestered you about passive voice enough? You still want more? : )