* make it a story. If you are writing about an application framework, use an example application and make it something real (a todo app, a real estate search app, something you have personal experience with).
* link to your other stuff. He has a good point about sidebars (don't do it), but if you have written about something tangential previously, links are a nice way to avoid that. Works for pointing to other people's work as well.
* just ship it. He alludes to this in the last point, but seriously, the perfect blog post that never is published is 100% worse than the 80% done blog post.
* remember that while you are obsessing over everything, your reader likely isn't. Recall how closely you read this article? That is how closely most readers will read anything you publish.
* start with the end in mind (the title and the conclusion should be related and the thread should run through it).
* kill your darlings. If something doesn't fit, no matter how interesting or witty it is, copy it off to some other doc (possibly for another article). Or delete it. Either way, remove it from your piece.
* If you don't write often, you won't have other things to link to
* If you don't write often, you'll have a habit of trying to make something perfect
* If you don't write often you obsess over things
* If you don't write often then it's hard to throw away a witty one-liner because you aren't sure when you'll get to use it next.
> Especially when you're starting off, quantity beats quality.
I agree with this so much. Nothing will help your writing more than doing more of it when you are starting out. Later you can read style guides or books (depending on the type of writing) but even then you still have to put it into practice.
Early in the morning, when mind is fresh, not after full day of meetings
Block off 2-3 hours
Caffeine, empty stomach-
Start with first draft and just brain dump. Don’t worry about details.. leave lots of <<fill this in later>>
Start in a notebook with pen and paper only, physically remove yourself from phone and computer, sketch your thoughts on paper and then go to computer to brain dump
Don’t aim for any amount.. no doc is too little
Don’t format, proof read, correct too much at the beginning
Little wine/beer/whiskey can help (but you probably don’t want to do this early in the morning)
Long Hot shower can help you gather your thoughts
Take a break when your brain is fried, walk around, come back to it fresh
I find that I always code better on an empty stomach while drinking a warm cup of coffee. Is that a scientific thing?
Especially in the case of technical jargon, it's a good middle ground to link to a relevant definition directly. That avoids the friction of a suboptimal in-line definition and the friction of forcing a multi-click lookup. A beautiful part of the internet is links :).
> Instead of leaving posts as a boring todo chore in the drafts folder, it's perfectly fine to just stop cold and publish if a wrap up doesn't flow naturally. Honestly, nobody cares.
While I agree with publishing incomplete content, I would argue that this is an exception to the "Don't caveat, just say it" section from earlier. It's often helpful to caveat incomplete content because it treats the reader with greater respect.
> Especially in the case of technical jargon, it's a good middle ground to link to a relevant definition directly. That avoids the friction of a suboptimal in-line definition and the friction of forcing a multi-click lookup. A beautiful part of the internet is links :).
I remember one personal website that's been linked on HN (https://www.gwern.net/) where hovering links show a preview of the page, a bit like wikipedia is doing, but not limited to the top, where it's possible to scroll up and down. I think a similar system could be interesting when dealing with technical subjects.
> I would frequently be familiar with one part of the source material, but have no way to skip it and only read the parts I was unfamiliar with.
This makes for so much cleaner articles. It's actually a bit similar to what waitbutwhy.com is doing with tooltips.
It might have some negative SEO implications (if you're worried about that) because if you hide a lot of content like that it could potentially be seen by search engines as keyword stuffing. But if SEO is a secondary concern (which it should be for reasonable people not obsessed about rankings) then this is an excellent solution. Would love to see this more widely adopted.
 While a 2k word article explaining something that could be explained in 200 words is not :facepalm:
I am taking a different approach with a new form I am experimenting with - the "Iceberg Article":
The idea is that there are two complete treatments of the subject - the "tip" which is highly compressed and the "body" which is fleshed out with notes, pictures, examples, subscripts, etc.:
"In this way, a concise and complete treatment of a subject can serve as a gateway to an extremely deep and rich well of content that does not distract from the parent work."
 Yes, I did start off properly referring to it as a "bummock" but I got sick of both reading and writing that word.
Site feedback for you, John: I would appreciate if you linkified your name (in the header of the page), as well as the path "breadcrumbs" at the right hand side of the header. Otherwise I'm stuck chopping things out of the URL by hand to try and go up the path.
 For instance, see this online copy of "Augmenting Human Intellect" (AHI). https://dougengelbart.org/content/view/138/ Notice how all the paragraphs are explicitly arranged in a hierarchy. At Engelbart's research lab, all documents were circulated in such a format ... even public releases like AHI ... and they had software with capabilities similar to today's org-mode, or Workflowy, or Vim folds which let researchers browse/edit code and text with respect to the hierarchy ... I highly recommend reading the linked report.
That doesn't fit my experience writing programming tutorials at all. The people reading them will not "google it". they'll just get confused that you didn't explain everything and they therefore got lost.
Certainly the top of the article lists pre-recs and links to them but it's surprising how many people will read lesson number 15 of 40 and skip lessons 1 through 14 and then complain that they didn't understand it. I end up having to spell it out. Bla bla bal (which we covered in lesson 3), does bla bla bla (covered in lesson 7) etc....
I haven't actually measured how often this is used, so it's hard to guage effectiveness, but I think it at least suggests to readers that you are trying to respect their time.
An example from my blog about price wicks, explaining how candlestick charts work: https://www.machow.ski/posts/scamwicks-and-stop-cascades/#ca...
You are right of course and I also always appreciate this when done well! Think you're right it's best used for stuff like technical jargon where very good and specific info can be difficult to find via an open-ended search.
> Honestly, nobody cares. The fun part's done, and most readers will detect the wrap up section of a post and will usually stop reading there anyway.
And that's how the text just ends - self+referential advice detected :)
So in my case I would say, be mindful of the difference between the two, and if you're stuck with one approach, don't hesitate to try the other.
At risk of being one of the nitpickers; I do quite enjoy reading caveats, also sidebars if either entertaining or informative. Very much agree that it should only be done if it benefits the story. I would say you strike a nice balance in your article haha.
The article's advice seems useful, so I may apply some of it to my growing mountain of 'unfinished' posts.
One thing I like to do is add HTML <details> elements for caveats or interesting tangents; these don't break up the main flow too much, their contents can be written pretty much separately from the main post, and they can be added/amended later if desired (e.g. if we find out something new and want to update an old post)
Caveats are sometimes in order. Other times not.
It’s impossible to say anything on the internet without someone commenting to correct your grammar, pointing out a niche where your argument breaks down, constructing straw man and weak man arguments to refute the credibility of your post, etc
It makes me never want to contribute at all anywhere
This, of course, results in boring and uniform writing.
Writing publicly visible texts like even comments is a hard thing to do for me. Even if I am sure I have something of value to add, I mull over all the variations of how to phrase my point and in the end just delete it.
Never mind writing a blog post, although I have played with the idea for a long time.
But sometimes you are forced to write, like for school/uni/work. And then I pretty much do all the things mentioned in OP's post, so this gives me something to think about.
Personally I love it when jargon is clearly defined in context and the arguments are constructed as if-then-else statements.
It depends. You have to let the reader know (i) what you're talking about, and (ii) what you're really saying. An example: Suppose you write about how taxes are bad. What do you mean by "taxes"? What else happens other than the tax change? What current event is behind your decision to write about the topic?
The author is right if there's an introductory paragraph with a dictionary definition of taxes and then describing how taxes are collected in the US. If the introductory paragraph provides different tax rates (income, capital gains, etc.) and explains what they cover, who pays them, and so on, it's useful to include. You should err on the side of too much background rather than too little.
I feel like this speaks to a general reluctance to accept uncertainty and shades of gray surrounding a topic. It often seems to me that many people prefer to have things neatly sorted into binary categories, supporting them either completely or not at all, when most topics resist this kind of neat division if given more than a cursory glance.
Articles refusing to include any nuanced discussion of a point and simply stating an arbitrary position as proven fact just exacerbates the problem.
It's not too hard to make a connection with the often-polarising and vitriolic nature of discussions online and the rise of misinformation.
I've found that you can have the best of both worlds here and use footnotes for sidebar material. I love reading articles with footnotes (they can be funny and delightful at times) but if someone doesn’t, they can easily ignore them.
For example, click on the dotted yellow links here: https://www.pcmaffey.com/roll-your-own-analytics/
2) Reread it out loud. If it doesn't sound right out loud, it isn't right
3) Rewrite it until it's what you want it to be
5) Don't worry about #3 in some cases. Sometimes good enough is good enough.
6) Don't polish a turd. If it's bad writing, throw it out, start over.
1. Give yourself permission to write badly.
2. Write what you want to read.
3. Find a writing buddy.
4. Set writing goals that are fun and achievable.
5. Celebrate your writing successes!