In case you want to fix it, I’ll share a minor mistake I saw in that linked blog post:

We are all speaking some sort of language, but none of us follow all the rules, and we all have some of our own. You might have noticed that in the previous sentence I joined two separate but related sentences with a comma. This is not grammatically correct in English - you’re supposed to use a semicolon.

Don’t worry, I’m not talking about a grammatical mistake you’re making to prove a point. I’m talking about an accidental lack of grammatical mistake.

The first sentence of my quote is already grammatically correct. The rule violation you’re describing is a comma splice, but the sentence is not an example of that. Because you added the coordinating conjunctions “but” and “and”, the commas are grammatical, and replacing either with a semicolon would make the sentence ungrammatical. The missing intentional grammatical mistake distracts from that paragraph’s main point.

score 1 · canonical

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

score 1 · canonical

Well allow me to counter with this position, based on lived experience as well as like experiences heard from friends, and observed with acquaintances.

But first, summary opinion about this and other antipatterns enumerated by OP and various commentators here:

The beauty of writing advice, like Any<Beauty>, resides in the eye of the beholder. I’d argue the question behind “patterns” v/s “antipatterns” is: Barring reasonable common law and constitutional rights+duties—and maybe the third party publishing service’s terms of use and content policies—who else ought to set editorial policy for a blog (and/or site) I personally author and operate? Why?

cat brain | # there is no such thing as a "useless cat"
     cat <(lobste.rs.content.before.this) \
         - \
         <(lobste.rs.content.after.this)

The answer to The Question may very well converge to mtlynch’s post, which, if one shares bloggerly purpose(s) with him, is advice worth adopting (and adapting).

Alas, a writer can do only so much to please the reading public’s roving eye. The writer will almost always disappoint most of the reading public who chances upon their publication (hence your normal 90%++ bounce rate). Besides, there is no accounting for taste. LLM technology has helped many people become, um, bloggers “content creators”. A section of the content-consuming public seem to prefer the uniform predictability of Any<BeautyFactory> wordsmithy.

In my book, it is each to their own. For “whimsy” and “just because” absolutely (and inviolably) belong to the set of “editorial policies”, whether the nature of the matter discussed by the content is serious or not.

The laws of nature all but guarantee that one’s anaemic site has little or no prospect of ever becoming anything more than a dangling pointer to the lone opening post in the “apology blog post” genre (my favourite blog post genre… they are all so different in content, yet so similar in sentiment). I wager this is true of all attempts to start blogging, whether it is wordpress, or blogger, or bearblog, or ghost, or notion/obsidian, or just plain text files thrown out in a github repo.

Given that reality, I think making a custom site builder is a worthwhile yak shave in and of itself, even if it becomes an endless project to tinker with locally, and sublimates one’s blog-publication energies. Both things can be true: a person is publishing (at some blog site, or more likely skeets or xeets or slacks)… and has a forever-work-in-progress custom site builder.

Further, I feel strongly that thinking in terms of “time taken” about custom personal software is not fun—and therefore not productive! Fun is the top reason, by far, to FAFO with custom hobby projects! Better to think of the site maker in terms of a custom emacs or vim configuration, which naturally mashes up with a fun-and-games self-education about the web.

Me, I reckon I spent over six months tinkering with various static site builders, and then spent a few more months hacking together my own from scratch (100% hand-rolled, including HTML and CSS, templates as heredocs, Bash to build and hot-refesh sans javascript, pandoc to compile content to HTML, jq and xmllint to escape stuff and to validate stuff respectively).

That brings me to two more “antipatterns”.

• M+One: Using crusty prickly funny-smelling software, like Bash of all the things, to make one’s site builder.

  Perl and PHP hackers of a certain vintage will roll their eyes even harder at this choice than contemporary nerds. To the lot of them I say, why not?! And I’m not alone in this as evidenced by the comments to this post: https://lobste.rs/s/70isfv/how_make_damn_website (several Persons of (shell) Culture in there :). See: “because, fun” as the prime mover of such an enterprise doomed to fail, unless much luck happens.

• M+Two: Someone pointed this out in a discord: Putting a “Part 1 of N” in the title without having the next part anywhere close to publication.

  And then finally not publishing the rest, because other shiny objects became suddenly more important. The “How to make a damn website” post discussed above did not do this, but I did, in all earnestness: shite: static sites from shell (part 1/2) — feeling the html.energy. (The subsequent drafts are still on disk… yes there will be a part 3 of 2 (and maybe a couple more), if the rest of the series ever sees the light of day.)

Bonus “antipattern”, in the same category as the parent comment; i.e. you probably aren’t going to do the thing, so why bother tooling about with the machinery…

• M+Three: Including a newsletter form from the get-go.

  My first newsletter email went out almost a whole year after I published my “apology genre” opener blog post, doffing one’s hat to Neal Stephenson, In the beginning, was the domain name. Unsurprisingly, that email was also an “apology genre” opener :D (excerpt below).

  I dithered a long while about whether or not to include a newsletter form, with legitimate foreboding that nothing would ever happen on the site. That hesitation, I firmly believe now, was due to acquired distaste; deep misgivings absorbed by osmosis from the popular discourse about what is the appropriately nerdy way to run a nerd blog (especially a nerd blog). We nerds skew “anti-sales” / “anti-marketing”, because the counterculture signalling Force is still strong with us; viz. “Oh how self-important and self-promoting does someone have to be to do that?!”.

  In fact, I rolled with the newsletter because I eventually recognised that (needlessly angsty) sentiment was nerfing my system.

October 6, 2022

Joy oh joy; a Yak was shaved, a site was published!

Hello friend!

Thank you for signing up for my “occasional newsletter” many moons ago!

Counting you, fourteen people signed up since evalapply.org first went live, late 2021. That figure is about 1,300% greater than my self-test email address, which I fully expected to still be hanging about all by itself.

A person signs up for a letter expecting one, sooner than later. I’m sorry I didn’t write sooner, particularly because newsletter signups were one of the few pleasant surprises in what has been a very long dark tea time of the soul.

So, first, a wish for you…

and so on. And for more entertainment… My comment over at the corresponding HN debate documents self-owns for all the original antipatterns :sweat-smile: :D

score 1 · canonical

If the goal is to get something written, of course. If the goal is to tinker with something that you enjoy, there’s no problem in endlessly redesigning your website with a single post on it.

score 1 · canonical

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.

score 1 · canonical

I’m also ambivalent about meandering introductions because “meandering” is in the eye of the reader, and introductions provide context, the reader may not have encountered the problems you have and the contextualisation is an answer to the question “why should I care”.

But of course that’s not a hard and fast rule, not everything is a war story, sometimes you’re showing off the cool knowledge rock you found, and that doesn’t require context, a cool rock is a cool rock.

score 1 · canonical

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.

But do still make sure lang is correct.

score 1 · canonical

Footnotes that are essentially mandatory reading instead of making them optional/bonus material (similar to your point about links)

I don’t mind this style on the printed page, and in fact I like it a lot. But when the footnotes become endnotes, whether printed or on a web page, or when they are links, I find it really bothersome. For me the difference is between flicking my eyes to the bottom of the page and having to break my reading by thumbing through pages, scrolling or clicking about.

score 1 · canonical

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

score 1 · canonical

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.

score 1 · canonical

I call the meandering intro “throat clearing”. It’s common because most people don’t write enough and it’s a warm-up for getting into the rest of the text; it’s their familiar territory that’s easy to write about.

A good rule of thumb is that you can usually delete the first three paragraphs of most technical blogs and then sub in a new lede that tells the reader what’s coming after the rest of the blog post has been written.

It’s better to have a link that few people click than to not have it, IMO. Of course, these days, links are tech debt - after a blog post has been up a few years, link rot sets in and half the links will be 404.

score 1 · canonical

I have a suspicion that nobody on the internet clicks links any more, if they ever did.

I click links. I love them. Maybe a bit too much though, since I tend to fall into recursive reading.

score 1 · canonical

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

score 1 · canonical

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.

score 1 · canonical

Thanks for reading!

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.

score 5 · canonical