What makes a word explanation good?

From Issawiki
Revision as of 14:07, 18 July 2021 by Issa (talk | contribs)
Jump to: navigation, search
  • 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!)
    • 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
  • 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
  • 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 extreme values
  • 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; they 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"
    • 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

See also

What links here