Live data from Hacker News

Patterns in Confusing Explanations

jvns.ca

41–50 of 168 posts

Re: Patterns in Confusing Explanations

#41
One of the major issues I have with new topics in computing is the amount of acronyms and the words and meaning behind them you get bombarded with. And you need to understand each one of them in order to understand the explanation you're dealing with.

Each acronym opens up a world full of new questions.

Re: Patterns in Confusing Explanations

#42
post #22

My default mindset used to be “I’m not getting this -> I’m stupid”, and I’ve been slowly shifting my mindset to “I’m not getting this -> this is probably not being explained well”

I find that it's usually a combination of both. What usually convinces me that we're reaching into the "I'm just not smart enough" territory is when I listen to multiple explanations from multiple sources and I'm still stuck (although ... I find that on certain subject people are just parroting each other a lot, which makes me often question whether the person doing the explaining actually understands the topic at al…

I think it’s usually less of a “I’m not smart enough” and more of a “this may take significant time to understand well.” Topics that are deemed too complex usually just require a significant amount of previous knowledge that you may not already have, and you just need to spend a lot of time thinking and learning about them. More on this here - https://www.benkuhn.net/thinkrealhard/

Re: Patterns in Confusing Explanations

#43
Very much agree on #1 and #2, and 6/7/8 in the same vein. Our internal documentation had a quality jump when we started to explicitly prefix documents with their intended audience.

For example, documentation targeted at our customer support assumes a basic familiarity with the monitoring systems and the structure of the customer facing services. However, documentation for the support cannot build on concepts like the network architecture, or shell access to servers.

On the other hand, documentation for operations engineers doesn't have to slow down the reader with information about the network architecture, as that's assumed to be known.

And being somewhat consistent with these documentation personas simplifies the onboarding of new employees, because there is a known knowledge base you need to access the documentation effectively.

Re: Patterns in Confusing Explanations

#45
post #41

One of the major issues I have with new topics in computing is the amount of acronyms and the words and meaning behind them you get bombarded with. And you need to understand each one of them in order to understand the explanation you're dealing with. Each acronym opens up a world full of new questions.

On the other hand one can't expect every single blog post, ie. on web service caching or whatever to spend first 50 pages on explaining TCP/IP, DNS, TLS, HTTP, WS protocol upgrade, JSON, JWT and what not.

If one finds too many unknown acronyms flying around and giving headache, it's probably a sign they should step back and sort out fundamentals in their head first?

Re: Patterns in Confusing Explanations

#46

Earlier quoted context omitted.

Learning by invention is also my favourite way to learn. However, I find it rather unappreciated among both teachers and textbook writers. What is usually done is the result is presented on a silver platter to regurgitate and reproduce, and important details are glossed over in favour of 'simplicity', creating a (dangerous) knowledge gap.

You remind me of something a Physics professor once told me. He said (I'm paraphrasing) "when you get to really learning the Physics, it's not an incremental logically consistent picture rooted in mathematics like in the textbooks. It's mostly a bunch of little tricks that you learn when to apply, and sometimes you get somewhere." He wasn't making a pedagogical point, but I wonder if being compelled by the "learn by…

To be fair, 'Learn by invention' can be detrimental if one is trying to derive a result which requires significant prior knowledge that the learner lacks. However, quoting a simple physics example of what I mean: One can prove the Work-Energy theorem with simple manipulations of the basic definitions of displacement, velocity and acceleration without having to learn it like a law. One cannot derive Newton's three laws, on the contrary.

Re: Patterns in Confusing Explanations

#47
My issue with pattern 12 (explaining the wrong way without saying it's wrong) isn't that I get confused about what is the right or wrong way of doing something, it's that I'll usually spend the time to actually develop examples, and if I was told up front that I was about to be shown the wrong way I would only read it so I didn't have to bother with the refactor during the learning.

Re: Patterns in Confusing Explanations

#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 pronouns with whatever they would refer to instead. Sometimes I also add an additional noun ("this practice") to make the pronoun clearer.

I still overuse pronouns sometimes, but when I want to be extra sure my point gets across, I'm trying to limit them as much as I can.

Re: Patterns in Confusing Explanations

#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 not) question that has somebody's idea of a "canonical" answer. That answer is often highly comprehensive but it is also often a poor fit answer for someone that is just trying to figure something out and is not equipped to handle and apply an abstract generalized solution to their specific problem.

Re: Patterns in Confusing Explanations

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

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).
Post reply on HN