Julia Evans is awesome. I would wholeheartedly suggest that you buy some of her zines if you can
Patterns in Confusing Explanations
81–90 of 168 posts
Re: Patterns in Confusing Explanations
#82Should these be anti-patterns? Perhaps calling something an anti-pattern is also a confusing way to explain things, or maybe that term has gone out of style now.
Re: Patterns in Confusing Explanations
#83One 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…
This not only applies to "it" but also to other jargon-y words that are used a lot in a single discussion. If you find that a single word is used disproportionally often in a discussion, it's almost always worth it to take a step back and ensure that everyone in the discussion has a shared (clear!) understanding of what that word means.
Re: Patterns in Confusing Explanations
#84A 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…
One tactic I use to avoid this is to ask myself “would a smart person who knows only what I’ve written up to this point about this subject understand what I just wrote?” If the answer is no, I need to break the concepts down more. I picture this as a tiny editor sitting on my shoulder who asks this question as I write.
Even that has problems. You might get into too much detail very fast.
Take the above examples on explaining something about git. It will depend immensely on what you need to explain and what you don't need to explain on what the context is and what you can assume is already known or not. This can work well enough if you have something self contained to document and you are the one documenting the whole thing. It falls apart quickly as things get larger and as more people work on it.
Pre-requisite reading that you assumed the reader went through before and "knows" are moved or slightly re-written. There are multiple paths to get to the part of the docs you're writing, some of which don't explain everything. Readers skip ahead because the pre-reqs are boring or over explaining some details they don't need or already know but that makes them miss the one important thing that they didn't know but is required for your part. If you re-explain it, your part might become this boring, skip-ahead part of the docs.
There are obviously techniques that can help with this, such as pointing towards pre-requisite documentation on a particular topic in case someone doesn't know already etc. Basically doing what you said, in a structured way with hyperlinks. In my experience, most documentation writers don't know how to do this properly/don't know the subject well enough and most developers that would know enough of the nitty gritty don't want to write documentation in the first place. There are just some very few (like you I presume) that are both good at this and like it. And many places won't let you do a good job of it, because you're supposed to be coding, not writing documentation for days.
Re: Patterns in Confusing Explanations
#85The person who wrote this is my spirit animal.
Re: Patterns in Confusing Explanations
#86One 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…
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…
This is a great practice, echoed by serious writers and technical writing guides.
Re: Patterns in Confusing Explanations
#87Often it’s not the explanation in itself that is confusing. It just takes some thinking and learning the terminology and jargon to develop a good understanding of a concept.
Information => confusion => more research => reformulate with your own words => finally reached a good grasp of the topic
That’s a very common way to learn about something and doesn’t have a lot to do with the quality of the initial information. You have to go through the process of being confused, then build your mental model of the thing.
Re: Patterns in Confusing Explanations
#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).
Re: Patterns in Confusing Explanations
#89A 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…
I try to fight this by defining any technical term immediately before or after the first time I use it. It makes you aware of stack depth if you find yourself defining a term within the definition of a term within the definition of a term, and may give you a hint you should reconsider the order of your explanation. It also helps you stay aware of your target audience if you stay aware of the words and phrases they're…
And in this day and age, we often provide the documentation as some type of digital document, and that can have "tool tips" for technical terms. Most word processors (Office Word, InDesign, LibreOffice) have some type of scripting capability, and that's a great way to make sure definition tool tips are on every usage of one's technical terms.
Re: Patterns in Confusing Explanations
#90I distinctly recall in CS102 being taught classes with the bicycle example. I'm glad I'm not the only one who was confused by that.