Live data from Hacker News

Patterns in Confusing Explanations

jvns.ca

161–168 of 168 posts

Re: Patterns in Confusing Explanations

#161
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…

Github’s dev assistant thing tries to fill in the code based on what you’ve written, by regurgitating prior knowledge almost blindly — but as a human I can process that regurgitation, and maybe extract a relevant subset of it for my actual use.

I’ve recently realized I do the exact same thing with speech — I’ll talk without thinking, forming sentences out of heuristic systems, and process them after the fact. Then tune the sentence slightly, and continue.

In this fashion, I produce sentences without really knowing what I’ve said, until I think about it later. In much the same way that I drive long distances on auto-pilot, and can’t even remember anything of the route by the end of it.

And those sentences often have ideas that I’ve never actually put together intentionally, but I completely agree with, and upon review, are correct to the best of my knowledge.

I don’t know what speech is, but it’s definitely more than vocalization of my thoughts.

Re: Patterns in Confusing Explanations

#162
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…

Pronouns unclear, please type $username instead of "I".

Re: Patterns in Confusing Explanations

#163
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…

Sometimes you just have to define variables. Customer C, supplier P, etc. That can get hard to read if done wrong, but better than dangling pronouns.

Even in CS papers, I've seen many clunky explanations that would benefit from introducing notation.

I think authors are sometimes reluctant to use a mathematical style when there's no theorem in the paper. They shouldn't be. Mathematical exposition can be useful for describing experiments and results too.

Re: Patterns in Confusing Explanations

#164

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.

Absolutely!

Re: Patterns in Confusing Explanations

#165
post #59

A lot of this is caused by The Curse of Knowledge : https://en.wikipedia.org/wiki/Curse_of_knowledge That cognitive blind spot causes people to unwittingly write confusing explanations in all domains of life. It's frequently ironic when somebody writes a sentence following the rhetorical template: "Not really sure what the confusion is with . It's really simple. [blah blah blah...] And that's it." Whether it's attemp…

> "monads are like a burrito" Wait, so a burrito is just a monoid in the category of endofunctors?

No, a burrito is like a non-Abelian subfield in the category of comestibles.

Re: Patterns in Confusing Explanations

#166
post #158
post #156

Earlier quoted context omitted.

In fiction writing this pattern known as “Burly Detective” Syndrome, see https://www.sfwa.org/2009/06/18/turkey-city-lexicon-a-primer... , https://tvtropes.org/pmwiki/pmwiki.php/Main/BurlyDetectiveSy...

Thanks so much, I didn't know there was a term for that! And it was hilarious reading about the UK's use of "popular orange vegetable" to refer to "carrots", a great example of taking this technique to the extreme. Fortunately, I don't think it's as bad to do that in fiction, because the author is going to establish how the world works to begin with, and therefore makes sure you have enough to know whether the altern…

[deleted]

Re: Patterns in Confusing Explanations

#168

Earlier quoted context omitted.

Swagger ‘documentation’. I understand every programmer I talk to loves this auto generated ‘documentation’ (prolly for selfish reasons). For me the tautological definitions, and lack of overview (which resources you need to form basic reporting—my introduction was swagger api for a Platform POS) undermine the description as ‘documentation’. I’m not complaining about what Swagger does, but about the cavalier way other…

The number one thing killing me about auto-generated API documentation is when an API takes a "string" that is really an enum and the generated documentation doesn't list out the enum values. Your only recourse is to read the code if it's open source and available in some obvious place, or hope there's a GUI alternative to the API with a pick list, select every option on the list, and intercept the internal API call…

GraphQL tooling exposes enums as such, I believe
Post reply on HN