Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Patterns in Confusing Explanations

jvns.ca

Post reply on HN
Print view View original

151–160 of 168 posts

Re: Patterns in Confusing Explanations

#151

Post by DavidPiper »

dmlorenzetti wrote: post #74
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…

This [0] helpful resource distinguishes between tutorials, reference material, how-to guides, and explanations. [0] https://documentation.divio.com

Oh wow, I literally have a blog post queued up about how different kinds of "documentation" can be split into similar categories. Great to see that someone else has had a similar insight!

My categories are Source (Reference), Procedures (~Tutorials), Examples (How-tos) and Meta (Tribal Knowledge, history, etc).

In the context of software teams (and others I'm sure) my anecdotal insight is that without a balance of these kinds of information, certain team functions break down:

- No Source/Reference, no shared deep understanding

- No Procedures, difficulty scaling processes (and difficulty onboarding new team members)

- No examples, harder to develop new skills / level up existing skills

- No meta, no context or "why", leading to less motivation

Re: Patterns in Confusing Explanations

#152

Post by aasasd »

behnamoh wrote: post #149
aasasd wrote: post #135

Earlier quoted context omitted.

> There was a post on HN a while ago which basically was about how using language (and probably, speaking out loud) is actually a `feature' or `technology' of human mind Really would like to see that post, as I've been vaguely interested in this very topic for quite a while. Is there a chance that you remember any key words that might've been in the title, so I could plug them into the HN search? From what I gathered…

Sure, I just found the post: https://psyche.co/ideas/talking-out-loud-to-yourself-is-a-te...

Thanks!

Re: Patterns in Confusing Explanations

#153

Post by satisfice »

NateEag wrote: post #133
satisfice wrote: post #38

I like the content! But I find that the use of exclamation points detracts from it! Maybe I am biased?! Because, for instance, I also avoid emoticons, and for the same reason! Which is: it can make the prose seem goofy and patronizing! But just in case you need exclamation points in order to hear what I write, I have used them in the comment!

Right there with you. I think it's an attempt to make the text 'feel' chipper, optimistic, and newbie-friendly. Julia writes some really good stuff, but that particular quirk in her writing has annoyed me for a long time.

She is definitely insightful and helpful. But all that fun-ctuation gets manic. I wonder “is she okay? do kidnappers have her family tied up in the basement?”

Re: Patterns in Confusing Explanations

#154

Post by Too »

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.

Not just why but also what. So many tutorials miss starting with a high level conceptual overview, and instead just spew out a long list of step-by-step commands to run without even explaining the effects that happen by each command. Or use some variation of pattern 1 from TFA, by only explaining it briefly using new and confusing terminology, like "to frobnicate the fluxiator we need to run 'flux --frob --now' "

I believe this is the main reason so many people struggle learning git, to use it effectively you need to understand the underlying data model, but instead people treat and teach it as a sequence of black-box commands. Once treading out of the happy-flow without understanding what, this sequence will not help you.

Fred Brooks famous quote also comes to mind: "Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious."

Re: Patterns in Confusing Explanations

#155

Post by hallgrim »

PoignardAzur wrote: post #130
josalhor wrote: post #101

Earlier quoted context omitted.

Have you seen 3Blue1Brown video about it? https://www.youtube.com/watch?v=aircAruvnKk

Yeah, I watched the series a few years ago, and it's still an example of the same problem. The videos give you a good vibe for what a NN network does, but they still stop at "if you can get the gradients using math wizardry, then you can train your network and do tons of cool stuff!" Meanwhile, if I had to write a neural network trainer from the ground up (even a very slow CPU one), I have no idea how I'd do it. Like…

I can recommend Andrew Trask’s tutorials and even his book on this. The (e-)book doesn’t go too in-depth with more complex NN applications, but you start out implementing your own NN from scratch using only numpy, which I thought was helpful to get into the topic.

Re: Patterns in Confusing Explanations

#156

Post by zczc »

SilasX wrote: post #114
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've seen newspapers handle this[1] by having other phrases for the same referent -- instead of just switching between "the pope" and "he", they'll slip in "the Bishop of Rome" or "the vicar of St. Peter". Unfortunately, I consider that itself annoying because it then creates the problem of assuming your reader knows which of those are just alternate phrases vs other entities in the story! Side note: this story got r…

In fiction writing this pattern known as “Burly Detective” Syndrome, see https://www.sfwa.org/2009/06/18/turkey-city-lexicon-a-primer..., https://tvtropes.org/pmwiki/pmwiki.php/Main/BurlyDetectiveSy...

Re: Patterns in Confusing Explanations

#157

Post by nonameiguess »

xtiansimon wrote: post #71
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…

Swagger ‘documentation’. I understand every programmer I talk to loves this auto generated ‘documentation’ (prolly for selfish reasons). For me the tautological definitions, and lack of overview (which resources you need to form basic reporting—my introduction was swagger api for a Platform POS) undermine the description as ‘documentation’. I’m not complaining about what Swagger does, but about the cavalier way other…

The number one thing killing me about auto-generated API documentation is when an API takes a "string" that is really an enum and the generated documentation doesn't list out the enum values. Your only recourse is to read the code if it's open source and available in some obvious place, or hope there's a GUI alternative to the API with a pick list, select every option on the list, and intercept the internal API call it makes to get the string representation of each allowed value.

Looking at you, Nexus Repository Manager.

Re: Patterns in Confusing Explanations

#158

Post by SilasX »

zczc wrote: post #156
SilasX wrote: post #114

Earlier quoted context omitted.

I've seen newspapers handle this[1] by having other phrases for the same referent -- instead of just switching between "the pope" and "he", they'll slip in "the Bishop of Rome" or "the vicar of St. Peter". Unfortunately, I consider that itself annoying because it then creates the problem of assuming your reader knows which of those are just alternate phrases vs other entities in the story! Side note: this story got r…

In fiction writing this pattern known as “Burly Detective” Syndrome, see https://www.sfwa.org/2009/06/18/turkey-city-lexicon-a-primer... , https://tvtropes.org/pmwiki/pmwiki.php/Main/BurlyDetectiveSy...

Thanks so much, I didn't know there was a term for that! And it was hilarious reading about the UK's use of "popular orange vegetable" to refer to "carrots", a great example of taking this technique to the extreme.

Fortunately, I don't think it's as bad to do that in fiction, because the author is going to establish how the world works to begin with, and therefore makes sure you have enough to know whether the alternate phrases mean that character or someone else, so, at worst, it's just cringey rather than confusing.

Re: Patterns in Confusing Explanations

#159

Post by rdiddly »

SilasX wrote: post #136
rdiddly wrote: post #128

Earlier quoted context omitted.

Someone tells you "the server crashed" and that's confusing? The list of things that happened after the connection attempt is one item: The server crashed. Unless you think the writer is actively trying to trick you, I think you can probably assume the client's crashing would be on the list if it had happened. It's a good convention to follow because cataloguing non-events is tedious: "I ate breakfast and did not cho…

Oh I thought the “it” version was being presented as less confusing.

Ah, no wonder!

Re: Patterns in Confusing Explanations

#160

Post by kazinator »

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…

Sometimes you just have to define variables. Customer C, supplier P, etc. That can get hard to read if done wrong, but better than dangling pronouns.
Post reply on HN