Patterns in Confusing Explanations • Hacker News Board

Re: Patterns in Confusing Explanations

#131

Post by NateEag » Sat, Aug 21, 2021, 8:12 PM UTC

crispyambulance wrote: post #49

The patterns Julia gives absolutely distill the bad practices when well-intentioned people try but fail to explain something. In particular, you can see examples of "inconsistent expectations of reader knowledge" and "starting out abstract" ALL THE TIME in stackoverflow. Someone will ask a specific question about a problem they're having but then have their question closed as dupe and referred to another related (or…

That does happen, but the StackOverflow people aren't wrong.

If there's a good, general answer to the question, then it's on the asker to expand their knowledge as they need to in order to understand that general answer.

Re: Patterns in Confusing Explanations

#132

Post by speeder » Sat, Aug 21, 2021, 8:13 PM UTC

gnuvince wrote: post #105

wasyl wrote: post #48

One tip I picked up a while back is to be aware of the number of `it`s and other pronouns used. I realized that when my explanation were getting lengthy, I was tempted to avoid duplication by referring to previously mentioned nouns as `it`s, `they`s etc. This practice led to some very confusing sentences, where each `it` meant a different thing. My explanations got noticeably clearer once I started replacing the pron…

That's a good one, especially if using pronouns causes people to have to backtrack in their reading. Another pattern that personally annoys me is when people use "the former" and "the latter"; I'm forced to go back in the text to remember which one was mentioned first and which one was mentioned second.

I get extra annoyed at this because I am not an English speaker and never remember what former and latter means.

Re: Patterns in Confusing Explanations

#133

Post by NateEag » Sat, Aug 21, 2021, 8:18 PM UTC

satisfice wrote: post #38

I like the content! But I find that the use of exclamation points detracts from it! Maybe I am biased?! Because, for instance, I also avoid emoticons, and for the same reason! Which is: it can make the prose seem goofy and patronizing! But just in case you need exclamation points in order to hear what I write, I have used them in the comment!

Right there with you.

I think it's an attempt to make the text 'feel' chipper, optimistic, and newbie-friendly.

Julia writes some really good stuff, but that particular quirk in her writing has annoyed me for a long time.

Re: Patterns in Confusing Explanations

#134

Post by secondcoming » Sat, Aug 21, 2021, 8:26 PM UTC

speeder wrote: post #132

gnuvince wrote: post #105

Earlier quoted context omitted.

That's a good one, especially if using pronouns causes people to have to backtrack in their reading. Another pattern that personally annoys me is when people use "the former" and "the latter"; I'm forced to go back in the text to remember which one was mentioned first and which one was mentioned second.

I get extra annoyed at this because I am not an English speaker and never remember what former and latter means.

latter = last, former = first.

Re: Patterns in Confusing Explanations

#135

Post by aasasd » Sat, Aug 21, 2021, 8:34 PM UTC

behnamoh wrote: post #122

aasasd wrote: post #78

Earlier quoted context omitted.

On the topic of low-level tips: IMO it helps to always try to read one's writing as if speaking it out loud. If the text doesn't flow well when spoken, then it's not good. Like, long-winded parentheses in the middle of a sentence are not good. Sure, the text won't look like those highbrow publications where you flex your mnemonic palaces just to remember what the sentence was about when it started—but at least actual…

For a long time I've tried to speed up my reading my turning off the `sub-vocalizing' machine in my mind, only to realize that sub-vocalizing actually helps understand the meaning of technical/math texts better. On a relevant note: There was a post on HN a while ago which basically was about how using language (and probably, speaking out loud) is actually a `feature' or `technology' of human mind. For long, we have b…

> There was a post on HN a while ago which basically was about how using language (and probably, speaking out loud) is actually a `feature' or `technology' of human mind

Really would like to see that post, as I've been vaguely interested in this very topic for quite a while. Is there a chance that you remember any key words that might've been in the title, so I could plug them into the HN search?

From what I gathered so far, one hypothesis is that language development went hand-in-hand with both consciousness and empathy, i.e. social cognition: as we learned to see the world from the viewpoint of others, we also expanded the abilities to communicate with others and think to ourselves.

Re: Patterns in Confusing Explanations

#136

Post by SilasX » Sat, Aug 21, 2021, 8:45 PM UTC

rdiddly wrote: post #128

SilasX wrote: post #113

Earlier quoted context omitted.

That's actually an example of making it more confusing. Did the client crash? Okay, it's obvious to you that the client didn't crash (but should it be obvious? Clients can crash too, you know!), but for anyone who didn't make the right inference, or isn't sure, they now have a dangling node in their mental model and are still validating they understood it right as they read the next sentences. If you really can't sta…

Someone tells you "the server crashed" and that's confusing? The list of things that happened after the connection attempt is one item: The server crashed. Unless you think the writer is actively trying to trick you, I think you can probably assume the client's crashing would be on the list if it had happened. It's a good convention to follow because cataloguing non-events is tedious: "I ate breakfast and did not cho…

Oh I thought the “it” version was being presented as less confusing.

Re: Patterns in Confusing Explanations

#137

Post by nemetroid » Sat, Aug 21, 2021, 8:46 PM UTC

> pattern 4: fun illustrations on dry explanations

The description restates this as "make the design reflect the style of the explanation", which I think is better, since it goes both ways.

I can't stand cutesy writing on technical topics, but I've nothing against cutesy drawings, so I can't agree with the title. But on the other hand, I've been disappointed a few times by "friendly style" writing hiding in dry visuals, so I guess I agree about wanting consistency.

Re: Patterns in Confusing Explanations

#138

Post by hinkley » Sat, Aug 21, 2021, 8:57 PM UTC

elboru wrote: post #12

Another pattern I usually encounter is explaining the how but not the why. Trying to understand how a complex mechanism works is hard, but it’s harder if you don’t know why the mechanism exists in the first place. It would be madness to start studying how an airplane engine works without knowing it is used to impulse a flying machine.

I keep trying to drill into people the fact that with so many people on a project, and so much jargon flying around, often people are going to be scanning docs looking for the right doc. You need an executive summary at the top of each page that basically sums up why someone would care to read this page, because odds are fairly good that they don't and if you beat around the bush then that feeling of being tricked into wasting time can result in some bad feelings about you or the project.

Re: Patterns in Confusing Explanations

#139

Post by abeyer » Sat, Aug 21, 2021, 9:04 PM UTC

bsenftner wrote: post #91

elboru wrote: post #12

Another pattern I usually encounter is explaining the how but not the why. Trying to understand how a complex mechanism works is hard, but it’s harder if you don’t know why the mechanism exists in the first place. It would be madness to start studying how an airplane engine works without knowing it is used to impulse a flying machine.

If we start asking "why" a huge proportion of many programmer's favorite tools would be thrown away - so asking "why" is an unexpected minefield in some circles. It forces an evaluation the "technical lead" (that set up the habit of these tools) and that is far too touchy for many "leads".

> asking "why" is an unexpected minefield in some circles

I suspect this largely stems from too many cases of not asking "Why do we X?" but rather "Why do we X instead of silver bullet/fad of the week Y that will fix all our problems?" Many of those technical leads have spent years fending off an onslaught of "obviously better" tools/processes/etc... that even if they _were_ actually an improvement would have grown to consume all available time in switching costs alone.

Re: Patterns in Confusing Explanations

#140

Post by nerdponx » Sat, Aug 21, 2021, 9:07 PM UTC

chefandy wrote: post #67

I'd add: over-verbosity, or conversely, seeing terseness as a goal in itself. A pet peeve on a smaller order: bad variable/function naming in beginner examples. Hypothetical: You're writing a true beginner tutorial introducing the core concept of fooKinetic in your cool new gaming language. Many authors choose variable and function names similar to the concepts they're introducing, which adds unnecessary cognitive lo…

I would also offer that whitespace and commenting needs are very different in "demo" code versus in "real" code. Even the font and syntax highlighting style can make the difference between a readable demo snippet and a meaningless blob.