Hacker News new | past | comments | ask | show | jobs | submit login
Tips for making writing more fun (davnicwil.com)
242 points by davnicwil on Jan 3, 2022 | hide | past | favorite | 64 comments

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

> Caffeine, empty stomach-

I find that I always code better on an empty stomach while drinking a warm cup of coffee. Is that a scientific thing?

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".

digestion isnt zero cost

I can't think unless I have something in my stomach, so I'm sure it depends on your metabolism or gut bacteria or who knows what.

> 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.

Gwern is love, Gwern is life.

I wanted a way to write both for people who were familiar with terms and for people who weren't, so I made Expounder:


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:

"Assume readers know the basics or will look them up ..."

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"[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.

FYI getting a certificate error there.

> 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.

An example from my blog about price wicks, explaining how candlestick charts work: https://www.machow.ski/posts/scamwicks-and-stop-cascades/#ca...

A <details> tag is also very nice for that.

> A beautiful part of the internet is links

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.

> it's perfectly fine to just stop cold and publish if a wrap up doesn't flow naturally.

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

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)

> At risk of being one of the nitpickers; I do quite enjoy reading caveats

Caveats are sometimes in order. Other times not.

It depends...

haha nice caveat ;), fully agree!

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.


To quote, "thanks, I needed to read this".

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.

Totally agree.

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.

Off-topic but English isn't my native lang and it'd help me if you can explain what "sound like a jersey" means. Google isn't helping. Is it an idiom?

I meant to say "jerk" but HN doesn't let me edit the comment anymore:P

The entire blog post could have been a bullet list if he followed his own suggestions #1 & #3.

I wouldn't have had as much fun writing that bullet point list, though :-)

I enjoyed reading this article (I needed to read this!) even though I’m already familiar with these bullet points. :)

Really glad it was useful :-) I'll also need to re-read the points regularly, before I write and after too as a quick pass self-proof-read!

Aren't you being the nitpicker here?

The post is just a bullet list with some elaboration on each point.

Isn’t every piece of writing?

No, some don't elaborate.

Yet all probably start as some sort of single statement or bullet point in some list.

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.

1) Write what YOU want to read

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.

> 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.

Though it's a rather deep rabbit hole to get Tufte-style side notes [1]. Crafting Interpreters does it quite nicely [2].

[1]: https://www.gwern.net/Sidenotes

[2]: https://craftinginterpreters.com/statements-and-state.html

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.

For example, click on the dotted yellow links here: https://www.pcmaffey.com/roll-your-own-analytics/

You have one of the most wonderful looking blogs I’ve ever seen!

Now i just need one of these for reading. Every time i get ten pages into a book it’s like my brain has to pee.

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.

Install SponsorBlock, or click the transcript and skim to where the interesting part starts.

For me these things work pretty good:

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!

Good article, but I have a nitpick with the w-- oh, I see what you did there.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact