Read on Twitter
I found this article by @jessejiryudavis quite insightful, particularly for its guidance on how to structure different types of articles on a programming blog. https://emptysqua.re/blog/write-an-excellent-programming-blog/
It's similar to the documentation framework I shared yesterday, in that it helps you settle on a single purpose for each new thing you write, with a corresponding tried-and-true format. https://twitter.com/davidklaing/status/1278130378750824448
Jesse's idea is that there are basically five types of posts:
- Stories
- Opinions
- How-tos
- Explanations of how something works
- Reviews
Each has its own linear format that works every time—or at least gives you some rules to thoughtfully break.
- Stories
- Opinions
- How-tos
- Explanations of how something works
- Reviews
Each has its own linear format that works every time—or at least gives you some rules to thoughtfully break.
Story:
1. Signal to the reader that this is a story (so that they can buckle up mentally).
2. Tell the story.
3. Say what the moral is.
Stories are nice to include on a blog (or whatever) because they let your readers get to know you a bit more intimately.
1. Signal to the reader that this is a story (so that they can buckle up mentally).
2. Tell the story.
3. Say what the moral is.
Stories are nice to include on a blog (or whatever) because they let your readers get to know you a bit more intimately.
Opinion:
1. Thesis.
2. Points of evidence.
3. Response to likely objections.
4. Restatement of thesis.
Basically the standard high-school essay. Doesn't need to long or fancy!
1. Thesis.
2. Points of evidence.
3. Response to likely objections.
4. Restatement of thesis.
Basically the standard high-school essay. Doesn't need to long or fancy!
How-to:
1. Say what the motivation is to do X—who, why, under what conditions.
2. Say how to do X.
3. Encourage the reader to go do X.
IMO points 1 and 3 are important if the topic is something grand, but less so if it's like "how to revert a commit." https://twitter.com/davidklaing/status/1278130380801900544
1. Say what the motivation is to do X—who, why, under what conditions.
2. Say how to do X.
3. Encourage the reader to go do X.
IMO points 1 and 3 are important if the topic is something grand, but less so if it's like "how to revert a commit." https://twitter.com/davidklaing/status/1278130380801900544
How something works:
1. Say: "Do you want to know how X works?"
2. Say how X works.
Jesse thinks it's unnecessary to explain the motivation in articles like these, because the intended audience is people who are curious about X—others can move along after answering "no" to 1.
1. Say: "Do you want to know how X works?"
2. Say how X works.
Jesse thinks it's unnecessary to explain the motivation in articles like these, because the intended audience is people who are curious about X—others can move along after answering "no" to 1.
Review:
1. Briefly describe the thing you're reviewing.
2. Say what your experience with it was like.
3. Say what its strengths and weaknesses are.
4. Say to whom & under what conditions you recommend it.
So much more useful than my instinct, i.e. "this thing is amazing"!
1. Briefly describe the thing you're reviewing.
2. Say what your experience with it was like.
3. Say what its strengths and weaknesses are.
4. Say to whom & under what conditions you recommend it.
So much more useful than my instinct, i.e. "this thing is amazing"!
