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.
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.
score 1 · canonical