Hacker News Reader

Comment by jasode | Hacker News Reader

A 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 <X>. It's really simple. [blah blah blah...] And that's it."

Whether it's attempting to explain "monads are like a burrito", or neural networks, Git, or how Federal Reserve works, people unintentionally write circular definitions.

E.g. "Not sure what the issue is... Git is just a DAG directed-acyclic-graph." <-- yes, in the mind of the author, that explanation is 100% self-explanatory!

The only way to avoid the issue is to test your tutorials and explanations on a variety of readers.

View on HN

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.

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.

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!"

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 get it! A neural network is a bunch of vector<float>! You change the weights in a way that is similar to finding the low point of a slope! Yes, every damn ML video uses the same metaphors! My question is, how do I actually change the values of the goddamn floats?!

I dunno. Maybe I need to watch the videos again and something will click.

EDIT: Okay, so the last video in that series is way closer to what I was looking for.

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.

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.

Sometimes people are just arrogant and want to make sure their audience really knows they (the speaker/writer) really know more.

> "monads are like a burrito"

Wait, so a burrito is just a monoid in the category of endofunctors?

No, a burrito is like a non-Abelian subfield in the category of comestibles.

Reply on news.ycombinator.com