Patterns in Confusing Explanations • Hacker News Board

Re: Patterns in Confusing Explanations

#91

Post by bsenftner » Sat, Aug 21, 2021, 2:38 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.

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

Re: Patterns in Confusing Explanations

#92

Post by benibela » Sat, Aug 21, 2021, 2:46 PM UTC

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 is why scientific papers have so much "let x be ..."

Re: Patterns in Confusing Explanations

#93

Post by SiempreViernes » Sat, Aug 21, 2021, 2:59 PM UTC

durbatuluk wrote: post #88

"I think" posts should always handled with care because we have no real evidence, just your "I think". Pattern 12 is often used to promote critical thinking and to shake previous believes. Most teachers want the class to realize something is wrong because this type of realization helps the process of learning (knowledge coming from you, not them).

In the case of 12 the objection is that the author is unfairly tricking (intentionally or not) the reader into making a mistake, which is unnecessarily hostile.

That's why one of the suggested fixes is simply to place a warning that the following is not to be read as reliable gospel.

Re: Patterns in Confusing Explanations

#94

Post by hammock » Sat, Aug 21, 2021, 3:04 PM UTC

frumiousirc wrote: post #77

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…

I agree that overuse of "it" is very confusing and in both the written word and in speech. Overuse of "it" is often a sign that the writer or speaker is not fully clear on the topic in their own mind. On the other hand, "under use" of "it" can also lend friction to understanding as "under use" of "it" destroys briefness. Cognitive load increases as we wade through "under use" of "it" again and again. A little bit of…

The important bit is not overuse or underuse, it's proper use. I was taught in high school rhetoric class:

all pronouns must have a clear, one-word antecedent.

This principle was drilled into my brain, and it's helpful.

Re: Patterns in Confusing Explanations

#95

Post by atoav » Sat, Aug 21, 2021, 3:07 PM UTC

benibela wrote: post #92

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 is why scientific papers have so much "let x be ..."

You can use variables, this is also done in philosophy where a philosopher will first define the precise meaning of a certain term they are using and then use it within further discussion. This is totally okay if done transparently and for a reason.

What is a pitfall however to declare these variables implicitly and rely on them too long. As a writer it is very easy to forget this because of course you know what topic you are writing about. As a reader however you have to do some work to get into the same (or similar) world of thinking as the one the writer created for you.

Same is true for speaking. Of course I know what I mean when I say something, but the other person might not even know what language I am speaking in and would have to decipher that first. In a similar way people have to decipher abstract topics you might be talking about

Re: Patterns in Confusing Explanations

#96

Post by 3pt14159 » Sat, Aug 21, 2021, 3:07 PM UTC

aasasd wrote: post #61

My long-standing annoyance with software documentation is when people don't see that tutorials and reference are different things. They may have tutorials as the only documentation available ( ahem Ansible cough ), or reference as the only documentation. But in fact, the use-cases for those two are different, so effectively they have different audiences. I don't want to learn a language from a dictionary, and I don't…

My biggest annoyance with software documentation is when it only has simple examples and doesn't mention obvious corner cases or covers the case where there is one related object but doesn't cover the case where there are multiple objects.

Re: Patterns in Confusing Explanations

#97

Post by touisteur » Sat, Aug 21, 2021, 3:15 PM UTC

nbernard wrote: post #50

touisteur wrote: post #23

Earlier quoted context omitted.

You'd enjoy Richard de Crespigny book, QF72, about the A380 in-flight engine explosion incident. One of the clearest reasons he could save the aircraft, is that he spent some time in France, meeting w/ the designers of the different subsystems, and asked (and was answered clearly) tons of 'why' questions. Yeah yeah 'how' is interesting but in the end, the 'why' is far more important, but also rememberable, and it hel…

For others looking into this book, it seems it is titled QF32, not QF72 (QF72 is linked to a different incident/pilot).

Every time I mess them up. Thanks.

Re: Patterns in Confusing Explanations

#98

Post by Ensorceled » Sat, Aug 21, 2021, 3:16 PM UTC

durbatuluk wrote: post #88

"I think" posts should always handled with care because we have no real evidence, just your "I think". Pattern 12 is often used to promote critical thinking and to shake previous believes. Most teachers want the class to realize something is wrong because this type of realization helps the process of learning (knowledge coming from you, not them).

From the article:

> pattern 12: explaining the “wrong” way to do something without saying it’s wrong

I encounter Pattern 12 in three different ways:

1. Google for solution problem. Find tutorial. See solution that, for all intents and purposes, looks correct. Adapt to my problem. Doesn't work. Return to to tutorial. "Surprise! How much time did you lose!?!?".

2. Following tutorial. See solution. Something seems off. Wrack my brain trying to reconcile the solution given that it seems wrong. Scroll down. "Surprise! That was the incorrect solution."

3. Following tutorial. See solution. Seems legit, integrate solution into my learning. "Surprise. Now your brain is broke!"

There is no version of this pattern that I've encountered where I didn't both treat the author as an unreliable narrator going forward and also assume they were a bit of an ass.

You can't learn if you no longer trust your guide.

Re: Patterns in Confusing Explanations

#99

Post by Ensorceled » Sat, Aug 21, 2021, 3:21 PM UTC

SiempreViernes wrote: post #93

durbatuluk wrote: post #88

"I think" posts should always handled with care because we have no real evidence, just your "I think". Pattern 12 is often used to promote critical thinking and to shake previous believes. Most teachers want the class to realize something is wrong because this type of realization helps the process of learning (knowledge coming from you, not them).

In the case of 12 the objection is that the author is unfairly tricking (intentionally or not) the reader into making a mistake, which is unnecessarily hostile. That's why one of the suggested fixes is simply to place a warning that the following is not to be read as reliable gospel.

Exactly. It doesn't even have to necessarily say "this is wrong" ... just something that causes you to engage with the example as potentially unreliable or not the best solution.

"The traditional way to solve this problem ..."

"Other tutorials suggest something like the following ..."

It's just sadistic to give an example that doesn't work and then I waste time looking for a syntax error or typo that doesn't exist.

Re: Patterns in Confusing Explanations

#100

Post by kaycebasques » Sat, Aug 21, 2021, 3:27 PM UTC

Meta comment: the author is applying the "invert, always invert" strategy to technical communication. I've never seen that done before. Style guides and quality control checklists are usually framed in the affirmative/positive. "Be concise." Etc.