Patterns in confusing explanations

source

50 highlights

• So why do I find all these explanations so confusing? I decided to try and find out! I came up with a list of 12 patterns that make explanations hard for me to understand.

• And the problem with positive patterns (like “avoid introducing unnecessary jargon”) is that they seem so obvious that I trick myself into thinking I’m following them, even when I’m not!

• I practically always write in a positive way (“X is a good practice!”) instead of in a negative way (“Y is a bad practice!”). So why am I writing about confusing patterns instead of writing about positive patterns?

• pattern 1: making outdated assumptions about the audience’s knowledge

• The reason this explanation is written this way is probably that the first edition of the book was published in 2009, and this assumption was probably true in 2009! Many people learning Git shortly after it was released were switching from Subversion or CVS or something and found comparisons like this helpful.

• But in 2021 Git has been the dominant version control system for a long time, and most people learning Git for the first time won’t have any experience with version control other than Git.

• It generally happens when the writer learned the concept many years ago, but doesn’t have a lot of experience explaining it in the present.

• So running an explanation by a few people who don’t already know the concept helps to catch incorrect assumptions I’ve made.

• pattern 2: having inconsistent expectations of the reader’s knowledge

• For example, a new language tutorial might explain a concept that almost all programmers would know, like how a for loop is used for iteration, while the writing that immediately follows implicitly assumes knowledge that many people don’t have, like how the stack works, how malloc works, etc.

• instead: pick 1 specific person and write for them!

• pattern 3: strained analogies

• This example is a parody, but I always find this type of analogy confusing because I end up wasting a lot of time trying to analyze exactly how an event stream is different / the same as the Mississippi river instead of just learning technical facts about event streams:

• instead: keep analogies to a single idea

• Instead of using “big” analogies where I explain in depth exactly how an event processing system is like a river, I prefer to explain the analogy in one or two sentences to make a specific point and then leave the analogy behind.

• option 1: use “implicit” metaphors

• Every event in a stream flows from a producer to a consumer.

• Here I’m using the word “flow”, which is definitely a water metaphor.

• option 2: use a very limited analogy

• pattern 4: fun illustrations on dry explanations

• We like batching. Batching is more efficient: doing ten at once is faster than doing one, one, two, one, one, etc. I don’t wash my socks as soon as I take them off, because lumping them in with the next load is free.

• The goal isn’t generally to trick the reader into expecting a more friendly explanation – I think the logic is usually more like “people like fun illustrations! let’s add some!“. But no matter what the intent, the problem is that the reader can end up feeling misled.

• instead: make the design reflect the style of the explanation

• pattern 5: unrealistic examples

• This kind of “real world example” is super common in object oriented programming explanations but I find it quite confusing – I’ve never implemented a bicycle or car in my code! It doesn’t tell me anything about what interfaces are useful for!

• pattern 6: jargon that doesn’t mean anything

• “Cryptographically secure” is unclear here because it sounds like it should have a specific technical meaning, but it’s not explained anywhere what’s actualy meant. Is it saying that Git uses SHA-1 to hash commits and it’s difficult to generate SHA-1 hash collisions? I don’t know!

• pattern 7: missing key information

• This paragraph is missing what to me is the main idea of content-addressable storage – that the key for a piece of content is a deterministic function of the content, usually a hash (though the page does later say that Git uses a SHA-1 hash)

• This pattern is hard to recognize as a reader because – how are you supposed to recognize that there’s a key idea missing when you don’t know what the key ideas are? So this is a case where a reviewer who understands the subject well can be really helpful.

• pattern 8: introducing too many concepts at a time

• instead: give each concept some space to breathe

• pattern 9: starting out abstract

• I start out by relating signals to the reader’s experience (“have you used kill? you’ve used signals!”) before explaining how they work.

• pattern 10: unsupported statements

• This says “In modern C, header files are crucial tools…” (which is true), but it doesn’t explain why header files are crucial. This of course wouldn’t be a problem if the audience already understood why header files in C are important (it’s a very fundamental concept!). But the whole point here is to explain header files, so it needs to be explained.

• pattern 11: no examples

• Another problem with the previous explanation of header files is – there aren’t any examples! Leaving out examples makes it harder for the reader to relate the new terminology to their own experiences.

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

• instead: here are four options for presenting mistakes

• I think the intention of this is to imitate the real-life experience of making mistakes. Usually when you make a mistake, you don’t know that it’s wrong at the time!

• And it’s possible that they would never even have made that particular mistake on their own!

• Talking about mistakes is very important, just say up front that the thing is a mistake!

• Tell a story about a mistake you made and why it caused problems

• Explain a common mistake (for example “Avoid Striding and Slicing in a Single Expression” in Effective Python)

• State an incorrect belief the reader might have: (“You might think that the command line tool would need to run as root (because it’s talking to the kernel, but…“)

• Frame the “wrong” thing as an experiment (“what if we try doing it X way?”)

• pattern 13: “what” without “why”

• I think one reason writers leave out the “why” is that it’s hard to write a simple universal answer to “why do people use Kubernetes?“. There are a lot of reasons! And if you get the “why” wrong, it’s very noticeable and it feels embarrassing. So it feels safer to just list some features and move on.

• But as a reader, I find that a weak “why” is much better than no “why”.