What makes a word explanation good?

I am focusing on word explanations here, so ignoring things like spaced repetition prompts, visuals, etc.

• Establishes the prerequisites/background the reader needs, and then builds on that background
• Simulates the reader's inexperienced state of mind
  • Anticipates common misinterpretations/misconceptions and counters them
  • Anticipates common questions the reader has
  • Does not assume infinite working memory (what goes wrong when this is violated: Unbounded working memory assumption in explanations)
  • When different words/terms/phrases are used to point to the same idea, this is explicitly pointed out (synonyms are very common even in technical fields!)
  • Points out which things are not important to worry about as a beginner, to focus the learner's attention
  • When the same word/term/phrase is used to refer to different ideas, this is pointed out (this is also very common even in technical fields!)
  • When defining things, give all four kinds of examples
  • Combat interference: when similar-seeming concepts are introduced in succession, pause to say whether or not they are the same
  • Warn reader about concepts that may become obsolete because they will be improved later on
• Considers all or many permutations of ideas (see permutation trick for a similar idea) -- actually it's more like sometimes when people write, they will implicitly establish a "table" with columns for attributes and rows for examples, and then they will fill in some of the cells but not others; example where this doesn't happen: https://github.com/riceissa/project-ideas/issues/18
• Alternates between concrete and abstract
  • Gives lots of examples throughout
• Actually gives a precise/technical/gears-level/mechanistic model for the reader to tinker with
• Each time you use a phrase, make sure the reader knows what the phrase means (this often turns into a problem when you use a vague phrase that could mean many things, or you use some really abstract-sounding phrase where the reader has no idea which concrete things it connects to; it's similar to vaguebooking)
• When introducing parameters and variables, consider both simple and extreme values
• Gives good mental representations
  • For example, when giving a definition in math, explains how people think about it in practice
• Structured as discovery fiction
  • Opens with the motivation for studying the topic, the "so what" -- one way to state this is, if people come to learn about a topic just because it sounds vaguely cool or because everyone else is talking about it, then when they read the motivation in your explanation, they should get really excited about the topic; the motivation you give should enhance whatever motivation the learned comes in with, rather than being a kind of "throwaway" motivation like you see in many textbooks about "how important this subject is". This raises the question of What counts as good motivation? This is actually a problem I see even in many pedagogically-inclined math exposition; fake motivation.
  • Gives motivation for steps throughout
  • Doesn't just give the crucial insight, but also the general heuristic one would use to discover such insights
  • Mentions obvious but failed approaches to the topic/things that don't work
  • Definitions last
• Prompting techniques
  • Gently invites the reader to think about things on their own first before reading the solution. But this needs to be done carefully, so as to enhance the reader's interest, rather than as a way to intimidate them. For more, see Managing micro-movements in learning.

See also

• Explanation science

External links

• https://issarice.com/math-explanations
• https://machinelearning.subwiki.org/wiki/User:IssaRice/Mental_representations_in_mathematics
• https://jvns.ca/blog/confusing-explanations/ https://news.ycombinator.com/item?id=28254630
• the video on this page also talks about some heuristics for making explanations good https://www.3blue1brown.com/blog/some1
• Judging textbooks by https://captchasamurai.github.io/homepage/index.html

What links here

• Unbounded working memory assumption in explanations ‎ (← links)
• We still don't know how to systematically write great word explanations ‎ (← links)