Other tips for making writing more fun, from someone who does it for a living (plus some other stuff #devrellife):
* 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.
I feel like a lot of these issues come up when people don't have a habit of writing often. Especially when you're starting off, quantity beats quality.
* 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.
Sure, writing is like anything else. It is usually more fun if you are doing more of it and getting better at it.
> 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.
After two years of doc writing at amazon, probably Over 1000 pages of content at this point-
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 can only conjecture.. the caffeine energizes something to help get s*it done. The empty stomach, something biological about, like when you’re full, your body is like ok I’m alive I’m satiated, don’t need to hunt. Coding is like hunting, you gotta kill the bugs so empty stomach is better.
My guess is that when we were hunter-gatherers, one of the strongest motivations for us to go out of the cave was an empty stomach. I am purposefully keeping myself a little hungry during working hours. The idea is that my body will keep sending signals to my brain to "not slack off".
> Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away.
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.
> > Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away.
> 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.
That's a work of art. It works recursively and windows can be pinned, expanded, or closed. You are free to go down the rabbit hole as far as you like and exiting the rabbit hole is a mere cursor movement away.
It reminds me of the zigzag data structure and Xanadu project. I try to emulate these sorts of ui's in my own experiments. It feels more intuitive, spatially.
This is brilliant! I completely agree with the premise:
> 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[0]. 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.
[0] While a 2k word article explaining something that could be explained in 200 words is not :facepalm:
The idea is that there are two complete treatments of the subject - the "tip" which is highly compressed and the "body"[1] 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."
[1] Yes, I did start off properly referring to it as a "bummock" but I got sick of both reading and writing that word.
Always happy to see someone writing in a hierarchical format. Maybe one day everyone will wake up and start writing Engelbart-style tree documents[1].
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.
[1] 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.
> Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away
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....
Recently I've got into the habit of doing both. Typically if there is a topic that is important to understand for a casual reader, but likely will be obvious for someone familiar with the topic i add a "click here to skip" link.
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.
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.
My biggest tip (based on my own experience): if you want to write something, record yourself speaking, then transcribe and edit only if necessary. The brain effortlessly produces sentence after sentence that flow pretty well when it's in verbal mode. The words just come to you with little to no reaching, unlike when writing and trying to think of the best way to put something.
For me it's the complete opposite, but your point is still useful in the sense of realising the two approaches aren't equivalent, and can in fact be complementary and produce different thought patterns.
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.
Nice article! I can see how that can make writing more fun.
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.
I've found I spend too much time on caveats and 'sidebars', which slows down my writing; the resulting text also gets too meandering and hard to follow, so I'll spend even longer trying to improve it; then it gets too dense; and so on.
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)
I really resonated with the tip about defensive writing. I do it all the time here and on Reddit.
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
Erik Hoel raised a really similar point in his substack - that the vast majority of literary fiction writers now study it, as opposed to no education or diverse education. They have spent a lot of time in workshops and create writing classes, and are thus experts in "minimizing attack vectors" in their writing.
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.
It depends on the content. Generally I'd say the one idea per paragraph and topic sentence followed by arguments approach is the best because it's the most common way of argument construction.
Personally I love it when jargon is clearly defined in context and the arguments are constructed as if-then-else statements.
> Cut out explanations of stuff you're about to write about. The danger zone for these is introductory paragraphs.
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.
What the author calls "caveats" I call being clear and precise. Too much of that can become a drag, but reasoning without some kind of nuance, exceptions, etc, is just too weak, and will only persuade those that already agree with you. You may also sound like a jersey.
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 don't really agree with his advice on caveats. Yes, they can certainly go overboard...but giving your reader a reason to go to Google is a potentially lost reader whose eyes are suddenly not on your article but a dozen clicks away reading something else.
> Everything is full of interesting sidebars, but sidebars like caveats just make for boring reading for someone who's presumably there for the title topic.
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.
On the web, inline/expandable “footnotes” are totally doable and provide a reader who enjoys sidebars and tangents the optimal ux, without jumping around.
Yeah those are nicely done. I like my own implementation, which overcomes the problem of limited width for the aside. In effect, its like unfolding a longer bit of the article.
Having an audience helps tremendously. I remember reading that children write better when they knew someone will read their stories. I imagine they are more motivated to write too (although on second thought, I can imagine it works the other way -- it could scare people off).
The same holds for things like video. During corona times, I've developed a habit to watch videos about interesting subjects when eating lunch. So many videos about energy production technologies start with long stock footage pieces about climate change. I already know.
This is why I can’t watch informational videos. There’s no easy way to skip past the introduction. You either skip too little or too far. So I try to stick to reading, where I can scan and skip and go back or forward easily.
I recently tried to watch a video on reflowing a GPU with a heat gun. The video was 40 minutes long. I don't remember how far I skipped into the video, but he had about a dozen cards lined up, and he was naming the model of each card one...after...the...other. I left for another video, so I don't know if he ever got to the point, and that's the kicker for me: Sometimes these videos never instruct.
