Or not having the date at all! Way too often I find myself digging around in view-source to try and find any indication of a date in metadata or whatever. I that fails I hit the Internet Archive and hope they've recorded the earliest known date for the post.
When something was posted is crucial context for understanding the perspective of the author.
Honestly, I'm at the point where I'd prefer not having the date to the articles that list the month and day, but not the year. Was this "Published: October 1st" article written last week, or during the closing ceremony for the Sydney Olympics?
Footnotes are always a mandatory disruption to the flow of reading, because readers can’t tell up front whether a footnote is worth the effort or not. Like when reading on paper, a footnote should always be in view and never require interaction, so it can be read with just a glance. Which implies that on a web page it’s better to lay out that kind of thing as an aside, without trying to emulate paper footnotes.
“Footnotes” on web pages are more like endnotes in books, where you have to keep an extra finger between the pages and repeatedly flip back and forth. (Even worse if the endnotes are used for both citations and commentary!)
I don't think I have seen this pattern elsewhere on narrow screens. They really are "footnotes!" Myself, I have recently switched to CSS anchor positioning to have margin notes falling back below the current paragraph if the viewport is not wide enough.
The #1 antipattern: investing 2 months into building a custom blogging platform, then 2 hours into writing your first blog post to introduce yourself and explain what you will blog about, then ... nothing.
If you are writing regularly, you are already in the top 5% (maybe top 1%). There is still room to get better, but remember to celebrate what you ARE achieving.
My rule is to try to add "time spent on published posts" as a positive number, and "time hacking on the technical aspects of the site" as a negative number; keep a running sum, and keep it positive.
So, if it takes me an hour to write "my first blog post"- great, now I have an hour to set up an SSG. If I spend an hour writing "here is a great design for a custom blogging platform," great, now I have an hour to write the code.
I enjoy working on the blog code itself. It's the most personal project I have and I am the only one relying on it. Sure, sometimes, you are distracted instead of writing useful content, but the blog being a hobby, I don't see as a bad think.
On the "meandering intro" - I find the inverted pyramid helpful. Assume that many people won't get past the first paragraph, so try to deliver the core message there.
"Overreliance on links" makes me sad. I love linking to things. I have a suspicion that nobody on the internet clicks links any more, if they ever did.
"Drop the formality. Write the way you speak in real life." - 100% agree. You have a voice, use it! This is also where LLM writing really hurts you, it eliminates that voice, and people can tell.
"Overreliance on links" makes me sad. I love linking to things. I have a suspicion that nobody on the internet clicks links any more, if they ever did.
I think we probably agree on how to use links.
I link heavily too, so I don't think there's anything wrong with linking itself. My rule of thumb is that my article should still make sense to the reader even if they don't click any links. That's the sense I get when I read your blog too. You offer links so the reader can dig deeper, but you don't expect the reader to stop and read every link.
The ideal html-document should should still be readable even if you removed everything inside angle-parantheses. Of course for a lot of interactive content this is impossible, but for blogs it should be doable.
Yeah the inverted pyramid is pretty much the template for all my technical blog posts. Very rarely goes wrong.
"Overreliance on links" makes me sad. I love linking to things. I have a suspicion that nobody on the internet clicks links any more, if they ever did.
I generally find websites in general tend to not link nearly enough. There's a crap ton of websites with nearly no outbound links what so ever, I think in some misguided attempt to keep the visitor from leaving.
Though link-rot is a legitimate concern and a pretty big problem, but I don't think not linking is the answer.
"Drop the formality. Write the way you speak in real life." - 100% agree. You have a voice, use it!
I don't speak the same way to everyone in every situation, that would be weird. Formal language doesn't have to lack a voice, though it demands familiarity with that writing style to shine through.
I think "reliance" is the keyword. As @mtlynch & @JulianSildenLanglo commented below, the references shouldn't be required reading to continue. Otherwise, the reading experience feels like a async runtime, switching tasks at every "await" (hyperlink)!
Please don't hotlink images: It sucks for both parties, you're now dependant on someone else, they're now suffering your potentially unwanted traffic.
It's okay to not add images if you have nothing relevant: Or at the very least get some royalty-free stuff, being flashbanged with some Stable Diffusion nightmare when I click on an article is very demoralizing.
Sort out your headers and tags: Setting up preload / preconnect / defer, and navigation hints are a low and one-time time cost to making your site feel snappier without having to really change anything about your content. Setting the langattribute on your top level is also a cheap win for better hyphenation and (from what I've heard) screen reader support. OpenGraph won't make your page faster, but it's a very simple way of allowing nice popups nearly everywhere.
Host fonts locally: Privacy conscientious people will thank you. The rest will also thank you for better caching and faster loads.
Throw your site into Dillo or a CLI browser every once in a while: It can help show issues in your HTML, that "modern" browsers silently paper over.
Sort out your headers and tags: Setting up preload / preconnect / defer, and navigation hints are a low and one-time time cost to making your site feel snappier without having to really change anything about your content.
Few blogging sites should benefit from these things. Preconnect? You should only be loading first-party resources, and if you’re doing something like analytics on another origin, you don’t want to prioritise that. Preload? Simplifying very slightly and with the possible exception of web fonts, if inserting such things manually makes a difference, you were doing the wrong thing. (The sorts of sites with piles of chunked JavaScript that may benefit from it use build systems that generate that.) Defer? Honestly it’s almost never what you actually want, you typically want <script> or <script async>.
Setting the lang attribute on your top level is also a cheap win for better hyphenation
I don’t believe any user agent stylesheets hyphenate by default, and I don’t think your stylesheet should enable it either. My vague feeling is that consensus has steadily been creeping up that hyphenation is just a bad idea in general, along with justifying prose on any but very narrow columns like newsprint.
My vague feeling is that consensus has steadily been creeping up that hyphenation is just a bad idea in general, along with justifying prose on any but very narrow columns like newsprint.
Hyphenation is necessary for full justification, and full justification is indispensable for any long-form body text. It's actually hardest to do well in narrow columns. If it has fallen out of favor worth web designers, it's more probably a matter of form following function -- designers first abandoning it because web browsers never implemented it well, then deciding they must not have wanted it all along.
One of my favorite tricks: chop the entire first paragraph and see if the post is still readable. If it is, it’s probably better off that way. Then repeat!
Always felt weird about the style of blogs I write, so the reassurance that you can chill out is refreshing. Do you have any tips on creating/thinking about the list of things your reader might know // how you'd determine who your reader is likely to be?
Do you have any tips on creating/thinking about the list of things your reader might know // how you'd determine who your reader is likely to be?
I personally imagine writing for my past self, before I started learning about a topic. I know other bloggers think of one of their friends and base it on conversations they've had with the friend.
I also find it helpful to write out an explicit list of things the target reader would know and what they don't know. You don't have to capture every single term you use in your article but setting the baseline like that helps you make decisions about other terms. Like, "I'm assuming the reader has never heard of git, but I tell them to use dig, so I should probably explain dig."
I think writing out a list is also a good opportunity to check whether you're writing for a sensible target audience. I've worked with a lot of bloggers who are like, "This post is for web developers with 2-3 years of experience," and so I ask how much would have to change for it to be accessible to beginner developers, and they're usually like, "Oh, huh. I'd only have to add two sentences to explain two terms." So, I think deciding which terms you assume the reader knows can be an iterative process as you decide what kind of article you want to write and what kind of reader you hope it benefits.
This is a good post all around! I agree with most points, but I also think it's incomplete without saying that there are exceptions to some of these rules, and you can execute them pretty well! For example:
The meandering intro: you always want readers to want to read your post. But there are ways to do that other than matter-of-fact statements and clickbait. For example, some people might follow you for your personality, because they're interested in what you're doing. Unique styles, well-designed pages that catch attention at first glance, or just being vaguely prominent can give you such an audience. Of course, this most often only works for existing readers, so you might want to use different styles in different posts.
The reader knows everything I know except this one thing: you do want to minimize the number of unnecessarily referenced complex topics, but if you overdo it, you just won't have anything useful to say. There's no good way explain how Docker works internally to someone who doesn't understand how Linux works, or to write a post on newly proposed Rust features to someone who never touched type theory. So when this post says "minimize assumptions about your reader", that doesn't mean to write for the lowest common denominator, it means choosing your intended audience deliberately. And it's fine if you want to keep the content deeply technical, we need that too!
The sequel injection bug: I think Raymond Chen makes this work. Many of his posts link to a previous post in the first paragraph, and that paragraph is a summary of that post. As in, the entire paragraph is a link, or at least a large part of it is. This feels quite intuitive, and I think it works because there is no textual hinting to read the prequel. Also, if you want to refer to a previous post that is only loosely related (e.g. it covers a different feature that you've worked on in the same project), don't make it feel like a prequel, just treat it like any other link and you can keep it.
I think making your blog require JavaScript is a pretty good indicator you aren’t hitting your target audience of technical readers. Many of us come in on browsers without JavaScript or JavaScript in allowlist mode since the internet is full of hostile nonsense—so why would I assume a random blog also isn’t in this category (or at least have the courtesy to show a <noscript> that explains what’s actually being missed)?
i was recently rewatching the classic sandi metz talk all the little things and there's a moment where she drops "duplication is far cheaper than the wrong abstraction" and says
the first rule we teach novices is "don't repeat yourself"—DRY but have you ever thought about why we teach them that rule? it's because they can't understand anything else. they don't know anything! but by god, they can recognize duplication! and it's a good rule! i'm not saying it's a bad rule. but now you've grown up, you know more, you have enough experience to tolerate a little duplication and wait on a better abstraction.
one of the biggest "media engagement hacks" is to generate a Take so atomic that your income is powered through the sheer number of clapbacks it generates. if that's your goal, so be it. but i think that as a writer, blogger, whatever you think of yourself, you are allowed to write however you want, to formulate your thoughts as you see fit, to use excessive links, or to be flowery in your prose, to make assumptions about your audience, or design your page however. we have so many spaces where the code we write or emails we send or takes we have must fit within the confines of some extant style guide or database column, but my claim is that your blog is your space to be yourself and there's nothing forcing you to write a blog "that performs well."
as you write more, you'll find what works to best communicate your thoughts and what doesn't, there is no one-size-fits-all set of edicts or prescriptions. thinking of anti-patterns in tech writing, i think the biggest one is transitioning from a person who writes about topics in tech that interest them, to becoming a person who hunts around for topics they think others will be interested in reading about. the former is a hobby, the latter is jobbing.
the farthest extreme of software blogging is writing about other people's writing in order to market your non-software content. there's no wrong place to be on the spectrum of hobby to professional blogger, but i find that people who vocally prescribe rules for others, be it in fashion, writing, art, or other avenues of self expression have lost sight of where they have ended up. for the rest of us, it is good to remember that we're grown ups, we know more, and we have enough experience to gradually develop our own practice in a way that enriches us best.
I think we're probably more in agreement than you think.
Like the Sandi Metz talk, I don't think these are rules that everyone has to follow strictly. These are rules of thumb that are meant to help bloggers who have trouble finding people interested in their writing. As bloggers gain more experience, they can develop more nuanced decisions on my guidance.
we have so many spaces where the code we write or emails we send or takes we have must fit within the confines of some extant style guide or database column, but my claim is that your blog is your space to be yourself and there's nothing forcing you to write a blog "that performs well."
This is true, and if someone is blogging for the joy of blogging and has no interest in what happens after they hit publish, then this is not a useful post for them.
The vast majority of bloggers I talk to do care about what happens after they hit publish, though. They don't aspire to be famous, but I rarely see bloggers say that they truly don't care about whether anyone reads their writing. They're interested in avoiding mistakes that drive away potential readers.
i find that people who vocally prescribe rules for others, be it in fashion, writing, art, or other avenues of self expression have lost sight of where they have ended up. for the rest of us, it is good to remember that we're grown ups, we know more, and we have enough experience to gradually develop our own practice in a way that enriches us best.
I'm having trouble understanding what your position is.
If someone is experienced in an activity, they shouldn't share what they've learned about that activity? Or are you specifically against teaching in the form of "rules?" Does Scott Meyers require some self-reflection in your view for writing rules like "Use const wherever possible" in Effective C++?
I had a large answer written, but Joel Spolsky had already a better answer to a similar kind of statement 26 years ago:
Jakob Nielsen says that Flash is “99% bad.” I have to agree. Flash always reduces usability.
On the other hand, every time I read Jakob Nielsen, I get this feeling that he really doesn’t appreciate that usability is not the most important thing on earth. Sure, usability is important (I wrote a whole book about it). But it is simply not everyone’s number one priority, nor should it be. You get the feeling that if Mr Nielsen designed a singles bar, it would be well lit, clean, with giant menus printed in Arial 14 point, and you’d never have to wait to get a drink. But nobody would go there, they would all be at Coyote Ugly Saloon pouring beer on each other.
While people may complain about meandering introductions, they are usually (as in the example provided,) sufficiently visually distinct that it's easy to skip over them. All this costs anyone is a little scroll.
However, asking authors to reïntroduce basic knowledge throughout, this tends to be mixed in with every paragraph, and it's much harder to skip. In fact, since many complex concepts require extensive background knowledge, the amount of space dedicated to “minimi[sing] assumptions about the reader's background knowledge” may rival that needed to describe the author's contributions to the topic. There is some sleight-of-hand in the example the author uses, but I can see where a reader may actually prefer the contraïndicated version, which is more interesting and has more “texture” than the alternative (which is bland, boring, and, in this case, misleading.)
Adding a link to shirk explication of some critical detail—sure, that's no good—but if the purpose of the post is to convey factual information, it seems like external (primary) sources are a critical piece. Again, I don't think the examples here really illustrate the point the author is trying to make, as the link is not particularly useful in either case, since it provides no practical supporting or corroborating information.
Honestly, I think the best modern advice is for authors is: if you need to be told this, then you shouldn't use an LLM to aid in your writing in any capacity. (If you didn't need to be told this, then you probably already knew how to use an LLM responsibly, and are at low risk of turning your writing into mushy goop.)
legoktm | 7 hours ago
This is great, two more anti-patterns I would add:
simonw | 7 hours ago
Or not having the date at all! Way too often I find myself digging around in view-source to try and find any indication of a date in metadata or whatever. I that fails I hit the Internet Archive and hope they've recorded the earliest known date for the post.
When something was posted is crucial context for understanding the perspective of the author.
rprospero | 6 hours ago
Honestly, I'm at the point where I'd prefer not having the date to the articles that list the month and day, but not the year. Was this "Published: October 1st" article written last week, or during the closing ceremony for the Sydney Olympics?
fanf | 6 hours ago
Footnotes are always a mandatory disruption to the flow of reading, because readers can’t tell up front whether a footnote is worth the effort or not. Like when reading on paper, a footnote should always be in view and never require interaction, so it can be read with just a glance. Which implies that on a web page it’s better to lay out that kind of thing as an aside, without trying to emulate paper footnotes.
“Footnotes” on web pages are more like endnotes in books, where you have to keep an extra finger between the pages and repeatedly flip back and forth. (Even worse if the endnotes are used for both citations and commentary!)
skobes | 3 hours ago
Agreed! I wrote a blog post about this.
https://basis.kobes.ca/20260726-doing-footnotes-wrong/
vbernat | 2 hours ago
I don't think I have seen this pattern elsewhere on narrow screens. They really are "footnotes!" Myself, I have recently switched to CSS anchor positioning to have margin notes falling back below the current paragraph if the viewport is not wide enough.
mcherm | 5 hours ago
The #1 antipattern: investing 2 months into building a custom blogging platform, then 2 hours into writing your first blog post to introduce yourself and explain what you will blog about, then ... nothing.
If you are writing regularly, you are already in the top 5% (maybe top 1%). There is still room to get better, but remember to celebrate what you ARE achieving.
cceckman | 4 hours ago
My rule is to try to add "time spent on published posts" as a positive number, and "time hacking on the technical aspects of the site" as a negative number; keep a running sum, and keep it positive.
So, if it takes me an hour to write "my first blog post"- great, now I have an hour to set up an SSG. If I spend an hour writing "here is a great design for a custom blogging platform," great, now I have an hour to write the code.
vbernat | 3 hours ago
I enjoy working on the blog code itself. It's the most personal project I have and I am the only one relying on it. Sure, sometimes, you are distracted instead of writing useful content, but the blog being a hobby, I don't see as a bad think.
cceckman | an hour ago
Sure; your time is yours, use it how you like!
simonw | 8 hours ago
On the "meandering intro" - I find the inverted pyramid helpful. Assume that many people won't get past the first paragraph, so try to deliver the core message there.
"Overreliance on links" makes me sad. I love linking to things. I have a suspicion that nobody on the internet clicks links any more, if they ever did.
"Drop the formality. Write the way you speak in real life." - 100% agree. You have a voice, use it! This is also where LLM writing really hurts you, it eliminates that voice, and people can tell.
[OP] mtlynch | 7 hours ago
I think we probably agree on how to use links.
I link heavily too, so I don't think there's anything wrong with linking itself. My rule of thumb is that my article should still make sense to the reader even if they don't click any links. That's the sense I get when I read your blog too. You offer links so the reader can dig deeper, but you don't expect the reader to stop and read every link.
JulianSildenLanglo | 7 hours ago
The ideal html-document should should still be readable even if you removed everything inside angle-parantheses. Of course for a lot of interactive content this is impossible, but for blogs it should be doable.
marginalia | 5 hours ago
Yeah the inverted pyramid is pretty much the template for all my technical blog posts. Very rarely goes wrong.
I generally find websites in general tend to not link nearly enough. There's a crap ton of websites with nearly no outbound links what so ever, I think in some misguided attempt to keep the visitor from leaving.
Though link-rot is a legitimate concern and a pretty big problem, but I don't think not linking is the answer.
I don't speak the same way to everyone in every situation, that would be weird. Formal language doesn't have to lack a voice, though it demands familiarity with that writing style to shine through.
hibachrach | 5 hours ago
I think "reliance" is the keyword. As @mtlynch & @JulianSildenLanglo commented below, the references shouldn't be required reading to continue. Otherwise, the reading experience feels like a async runtime, switching tasks at every "await" (hyperlink)!
Adrien-LUDWIG | 4 hours ago
I click links. I love them. Maybe a bit too much though, since I tend to fall into recursive reading.
nemin | 7 hours ago
Also for some more technical tips:
preload/preconnect/defer, and navigation hints are a low and one-time time cost to making your site feel snappier without having to really change anything about your content. Setting thelangattribute on your top level is also a cheap win for better hyphenation and (from what I've heard) screen reader support. OpenGraph won't make your page faster, but it's a very simple way of allowing nice popups nearly everywhere.chrismorgan | 5 hours ago
Few blogging sites should benefit from these things. Preconnect? You should only be loading first-party resources, and if you’re doing something like analytics on another origin, you don’t want to prioritise that. Preload? Simplifying very slightly and with the possible exception of web fonts, if inserting such things manually makes a difference, you were doing the wrong thing. (The sorts of sites with piles of chunked JavaScript that may benefit from it use build systems that generate that.) Defer? Honestly it’s almost never what you actually want, you typically want
<script>or<script async>.I don’t believe any user agent stylesheets hyphenate by default, and I don’t think your stylesheet should enable it either. My vague feeling is that consensus has steadily been creeping up that hyphenation is just a bad idea in general, along with justifying prose on any but very narrow columns like newsprint.
But do still make sure
langis correct.gcupc | 3 hours ago
Hyphenation is necessary for full justification, and full justification is indispensable for any long-form body text. It's actually hardest to do well in narrow columns. If it has fallen out of favor worth web designers, it's more probably a matter of form following function -- designers first abandoning it because web browsers never implemented it well, then deciding they must not have wanted it all along.
ur5us | an hour ago
…which might be hosted on CDN as opposed to the blog engine itself, so still legitimate IMO.
amw-zero | 7 hours ago
A better way to say this is: "know your audience and their background knowledge."
Always assuming the reader is a total beginner also doesn't lead to the best writing.
facundoolano | an hour ago
One of my favorite tricks: chop the entire first paragraph and see if the post is still readable. If it is, it’s probably better off that way. Then repeat!
amycodes | 8 hours ago
Always felt weird about the style of blogs I write, so the reassurance that you can chill out is refreshing. Do you have any tips on creating/thinking about the list of things your reader might know // how you'd determine who your reader is likely to be?
[OP] mtlynch | 8 hours ago
Thanks for reading!
I personally imagine writing for my past self, before I started learning about a topic. I know other bloggers think of one of their friends and base it on conversations they've had with the friend.
I also find it helpful to write out an explicit list of things the target reader would know and what they don't know. You don't have to capture every single term you use in your article but setting the baseline like that helps you make decisions about other terms. Like, "I'm assuming the reader has never heard of git, but I tell them to use dig, so I should probably explain dig."
I think writing out a list is also a good opportunity to check whether you're writing for a sensible target audience. I've worked with a lot of bloggers who are like, "This post is for web developers with 2-3 years of experience," and so I ask how much would have to change for it to be accessible to beginner developers, and they're usually like, "Oh, huh. I'd only have to add two sentences to explain two terms." So, I think deciding which terms you assume the reader knows can be an iterative process as you decide what kind of article you want to write and what kind of reader you hope it benefits.
purplesyringa | 5 hours ago
This is a good post all around! I agree with most points, but I also think it's incomplete without saying that there are exceptions to some of these rules, and you can execute them pretty well! For example:
The meandering intro: you always want readers to want to read your post. But there are ways to do that other than matter-of-fact statements and clickbait. For example, some people might follow you for your personality, because they're interested in what you're doing. Unique styles, well-designed pages that catch attention at first glance, or just being vaguely prominent can give you such an audience. Of course, this most often only works for existing readers, so you might want to use different styles in different posts.
The reader knows everything I know except this one thing: you do want to minimize the number of unnecessarily referenced complex topics, but if you overdo it, you just won't have anything useful to say. There's no good way explain how Docker works internally to someone who doesn't understand how Linux works, or to write a post on newly proposed Rust features to someone who never touched type theory. So when this post says "minimize assumptions about your reader", that doesn't mean to write for the lowest common denominator, it means choosing your intended audience deliberately. And it's fine if you want to keep the content deeply technical, we need that too!
The sequel injection bug: I think Raymond Chen makes this work. Many of his posts link to a previous post in the first paragraph, and that paragraph is a summary of that post. As in, the entire paragraph is a link, or at least a large part of it is. This feels quite intuitive, and I think it works because there is no textual hinting to read the prequel. Also, if you want to refer to a previous post that is only loosely related (e.g. it covers a different feature that you've worked on in the same project), don't make it feel like a prequel, just treat it like any other link and you can keep it.
toastal | 5 hours ago
I think making your blog require JavaScript is a pretty good indicator you aren’t hitting your target audience of technical readers. Many of us come in on browsers without JavaScript or JavaScript in allowlist mode since the internet is full of hostile nonsense—so why would I assume a random blog also isn’t in this category (or at least have the courtesy to show a
<noscript>that explains what’s actually being missed)?nsfmc | 3 hours ago
i was recently rewatching the classic sandi metz talk all the little things and there's a moment where she drops "duplication is far cheaper than the wrong abstraction" and says
one of the biggest "media engagement hacks" is to generate a Take so atomic that your income is powered through the sheer number of clapbacks it generates. if that's your goal, so be it. but i think that as a writer, blogger, whatever you think of yourself, you are allowed to write however you want, to formulate your thoughts as you see fit, to use excessive links, or to be flowery in your prose, to make assumptions about your audience, or design your page however. we have so many spaces where the code we write or emails we send or takes we have must fit within the confines of some extant style guide or database column, but my claim is that your blog is your space to be yourself and there's nothing forcing you to write a blog "that performs well."
as you write more, you'll find what works to best communicate your thoughts and what doesn't, there is no one-size-fits-all set of edicts or prescriptions. thinking of anti-patterns in tech writing, i think the biggest one is transitioning from a person who writes about topics in tech that interest them, to becoming a person who hunts around for topics they think others will be interested in reading about. the former is a hobby, the latter is jobbing.
the farthest extreme of software blogging is writing about other people's writing in order to market your non-software content. there's no wrong place to be on the spectrum of hobby to professional blogger, but i find that people who vocally prescribe rules for others, be it in fashion, writing, art, or other avenues of self expression have lost sight of where they have ended up. for the rest of us, it is good to remember that we're grown ups, we know more, and we have enough experience to gradually develop our own practice in a way that enriches us best.
[OP] mtlynch | 3 hours ago
I think we're probably more in agreement than you think.
Like the Sandi Metz talk, I don't think these are rules that everyone has to follow strictly. These are rules of thumb that are meant to help bloggers who have trouble finding people interested in their writing. As bloggers gain more experience, they can develop more nuanced decisions on my guidance.
This is true, and if someone is blogging for the joy of blogging and has no interest in what happens after they hit publish, then this is not a useful post for them.
The vast majority of bloggers I talk to do care about what happens after they hit publish, though. They don't aspire to be famous, but I rarely see bloggers say that they truly don't care about whether anyone reads their writing. They're interested in avoiding mistakes that drive away potential readers.
I'm having trouble understanding what your position is.
If someone is experienced in an activity, they shouldn't share what they've learned about that activity? Or are you specifically against teaching in the form of "rules?" Does Scott Meyers require some self-reflection in your view for writing rules like "Use
constwherever possible" in Effective C++?laurentbroy | 50 minutes ago
I had a large answer written, but Joel Spolsky had already a better answer to a similar kind of statement 26 years ago:
https://www.joelonsoftware.com/2000/11/02/20001102/
The only rule, if you ask me: if it is your blog, you write for you. Do what you like.
dutc | 6 hours ago
While people may complain about meandering introductions, they are usually (as in the example provided,) sufficiently visually distinct that it's easy to skip over them. All this costs anyone is a little scroll.
However, asking authors to reïntroduce basic knowledge throughout, this tends to be mixed in with every paragraph, and it's much harder to skip. In fact, since many complex concepts require extensive background knowledge, the amount of space dedicated to “minimi[sing] assumptions about the reader's background knowledge” may rival that needed to describe the author's contributions to the topic. There is some sleight-of-hand in the example the author uses, but I can see where a reader may actually prefer the contraïndicated version, which is more interesting and has more “texture” than the alternative (which is bland, boring, and, in this case, misleading.)
Adding a link to shirk explication of some critical detail—sure, that's no good—but if the purpose of the post is to convey factual information, it seems like external (primary) sources are a critical piece. Again, I don't think the examples here really illustrate the point the author is trying to make, as the link is not particularly useful in either case, since it provides no practical supporting or corroborating information.
Honestly, I think the best modern advice is for authors is: if you need to be told this, then you shouldn't use an LLM to aid in your writing in any capacity. (If you didn't need to be told this, then you probably already knew how to use an LLM responsibly, and are at low risk of turning your writing into mushy goop.)