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 want to wade through the tutorials when looking for one particular concept.
Patterns in Confusing Explanations
61–70 of 168 posts
Re: Patterns in Confusing Explanations
#62One 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 is one of the most helpful critiques I've ever received in my college english classes
Re: Patterns in Confusing Explanations
#63I write technical explanations for a living and are often baffled how bad some people write.
I don't even mean non-native speakers, but people from the UK/US.
People tend to leave out crucial information all the time and can't focus on what they try to explain. As if they don't read their texts after they've written them.
Re: Patterns in Confusing Explanations
#64My 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…
I think, reference only can work when it's really really good.
But generally you're right, guides/tutorials for the main use-cases speed up things drastically.
Re: Patterns in Confusing Explanations
#65My 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”
Yes! The same with movies (specially with thrillers, capers, noir, etc.). I always assumed I wasn’t paying enough attention and important bits of information flew over my head. As I got older and often when rewatching movies, I realized there’s a lot of hand waving, vague explanations and basically shoddy writing, even on big movies.
Re: Patterns in Confusing Explanations
#66Earlier quoted context omitted.
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/
Sure, it's a nice and egalitarian opinion and all but that doesn't take into account the situation when the guy next to you groks something 10 times faster than you do and can move on to the next topic in the blink of an eye.
As an extreme of this, if it takes you 20 years of hard study to grok a topic that normal people absorb in 6 months ... harsh to say, but you don't fall in the "smart" bucket.
Re: Patterns in Confusing Explanations
#67I'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 load for those who can't yet automatically visually parse the language. Someone who's looked at the code even for a couple of hours completely understands what `fook | fook ~~ fooKin | fook –– Fook{}` means, but to a complete language beginner, it's nonsensical. You lost an opportunity to reinforce your basic syntax, didn't communicate the core concept of the tutorial, and likely turned off people closer to the beginning of their coding journey.
Re: Patterns in Confusing Explanations
#68A 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.
Re: Patterns in Confusing Explanations
#69A 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…
Man, the bit about neural networks hits close to home.
I'd kill for a NN tutorial that doesn't go "Anyway, as you can see, by multiplying the derivative by a small value we can eventually find the local minima of this curve. Anyway, just use these exact tensorflow functions with the parameters we give you and you're all set!"
Re: Patterns in Confusing Explanations
#70A 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 not expected to know your usage of.