5 ms·

> The tutorial throws the user straight into the experience of using awk. There is no theoretical discussion first; there are no installation instructions; the

> The tutorial throws the user straight into the experience of using awk. There is no theoretical discussion first; there are no installation instructions; the first thing you see is an input example and a short program doing something with that input. They even get to the expected output on the very first page. Babies learn a language by hearing you talk. In other words, by example. No one has become fluent in a language through theoretical discourse and grammatical diagrams. That is counterintuitive. You would think you would learn better by having someone explain it to you, instead of throwing a mish-mash of examples your way. But that's not the truth. The truth is we learn by example and practice. Eventually you want the explanations, to round out your understanding. But it doesn't make sense until you have got your hands dirty. So that's a lesson for anyone wanting to teach anything. It's okay to have a little introduction, but try to get to concrete examples as soon as possible.

Benjammer 8y ago
Your comment reminds me of Lockhart's Lament[0] about how we (fail to) teach mathematics to children. It's a story about a world where we attempt to teach music in the manner that math is taught. Children rote-learn scales and musical theory from the beginning, building everything up until much later, when they are studying for a PhD, they finally are allowed to pick up a musical instrument and play for the first time, putting together everything they have learned over the years. The author compares this to how we learn mathematics and how only people in high-level applied math or engineering every actually get to use complex formulae in the real world and actually realize the inherent value of what they've been learning. [0]https://www.maa.org/external_archive/devlin/LockhartsLament.pdf https://www.maa.org/external_archive/devlin/LockhartsLament....
- deleted 8y ago
  [deleted]
svat 8y ago
Indeed. And this applies to mathematics too. Here is Ralph Boas, in Can We Make Mathematics Intelligible? following his own advice: > Suppose you want to teach the 'cat' concept to a very young child. Do you explain that a cat is a relatively small, primarily carnivorous mammal with retractable claws, a distinctive sonic output, etc.? I'll bet not. You probably show the kid a lot of different cats saying 'kitty' each time until it gets the idea. To put it more generally, generalizations are best made by abstraction from experience. (See also Tim (Sir Timothy) Gowers on Examples first: https://gowers.wordpress.com/2007/10/19/my-favourite-pedagogical-principle-examples-first/ https://gowers.wordpress.com/2007/10/19/my-favourite-pedagog... and https://gowers.wordpress.com/2007/10/24/examples-first-ii/ https://gowers.wordpress.com/2007/10/24/examples-first-ii/) (I frankly think this applies to the accursed phenomenon of monad tutorials in Haskell too (https://stackoverflow.com/questions/3261729/monad-in-non-programming-terms/3261837#3261837 https://stackoverflow.com/questions/3261729/monad-in-non-pro...), but some disagree.)
- hood_syntax 8y ago
  Along the lines of show, don't tell, the best one I've found is http://mightybyte.github.io/monad-challenges/ http://mightybyte.github.io/monad-challenges/ It helped me grok monads after I had a hazy understanding of them for a while.
- theoh 8y ago
  The idea of teaching using extensional definitions (an expanding list of examples) is fine, but I came across a weird case of it at a bicycle repair workshop a few years ago. It's a bizarre example, but it went like this. Audience: what's a fixed gear bike? Repair guy: it's uh, it's like a unicycle, for example... In that scenario an intensional definition is really the way to go. I don't understand how that bicycle repair guys mind worked at all.
  - deleted 8y ago
    [deleted]
  - kqr 8y ago
    Having ridden both fixies and unicycles, the example makes total sense. "It's like a pennyfarthing" works too. The issue is that examples are meant to leverage the recipients intuition. Very few people have intuition for unicycles and pennyfarthings, so the examples fall flat. That said, "It's like a children's unicycle" would probably count as a valid example too, and refers to something people may have intuition for. But it may also stress the wrong parts of the example. We want to convey the sense of direct drive, not circus prop.
    - lloydde 8y ago
      > That said, "It's like a children's unicycle" Tricycle? Or I’m very interested in a culture where children’s unicycles are a common thing.
      - kqr 8y ago
        Yes, tricycle, of course. If anyone figures out where this children's unicycle culture is I may want to move there.
cannam 8y ago
I recall "minimalism" in documentation being a theme during the 1990s, which I believe was influential in the design of documentation for Windows 95. I'd be interested in hearing more if anyone here knows about this. The origin text for this I believe was "The Nurnberg Funnel" by John M Carroll (https://mitpress.mit.edu/books/nurnberg-funnel https://mitpress.mit.edu/books/nurnberg-funnel) -- but I haven't read it. I have read a book of essays following up on it, "Minimalism Beyond the Nurnberg Funnel" https://mitpress.mit.edu/books/minimalism-beyond-nurnberg-funnel https://mitpress.mit.edu/books/minimalism-beyond-nurnberg-fu..., which I found quite inspiring. Both of the examples used here are older than that, which is also intriguing.
- kaycebasques 8y ago
  It's still one of the core technical writer philosophies. I have Minimalism Beyond The Nurnberg Funnel on my desk.
  - kqr 8y ago
    Interesting references. Thank you both!
cup-of-tea 8y ago
> Babies learn a language by hearing you talk. Babies take at least ten to fifteen years to become truly proficient with a language and that includes a lot of formal learning. Once a first language has been acquired the process of learning becomes much easier. Examples are very good, though. The Python documentation is usually very good at this. Examples often lead the sections with the exact details following.
- mediocrejoker 8y ago
  I think that's a pretty high bar to say someone is proficient with a language. Children as young as 1-2 can effectively communicate their thoughts and feelings with others. I would speculate there are many functional adults with language skills not much better than a typical 10-15 year old.
- mcguire 8y ago
  http://www.healthofchildren.com/L/Language-Development.html http://www.healthofchildren.com/L/Language-Development.html
e12e 8y ago
"The part of your body that plays tennis doesn't understand English. " to quote Alan Kay paraphrasing Timothy Gallwey ("The Inner Game of Tennis"). I don't think all explanation is redundant and counter-productive, but a lot of it is. I think it is useful to demonstrate how and explain why. If a stufmdent can internalize the correct motivation of why that can help choose which skill or technique to apply.

Benjammer 8y ago

Your comment reminds me of Lockhart's Lament[0] about how we (fail to) teach mathematics to children. It's a story about a world where we attempt to teach music in the manner that math is taught. Children rote-learn scales and musical theory from the beginning, building everything up until much later, when they are studying for a PhD, they finally are allowed to pick up a musical instrument and play for the first time, putting together everything they have learned over the years. The author compares this to how we learn mathematics and how only people in high-level applied math or engineering every actually get to use complex formulae in the real world and actually realize the inherent value of what they've been learning. [0]https://www.maa.org/external_archive/devlin/LockhartsLament.pdf https://www.maa.org/external_archive/devlin/LockhartsLament....

deleted 8y ago
[deleted]

svat 8y ago

Indeed. And this applies to mathematics too. Here is Ralph Boas, in Can We Make Mathematics Intelligible? following his own advice: > Suppose you want to teach the 'cat' concept to a very young child. Do you explain that a cat is a relatively small, primarily carnivorous mammal with retractable claws, a distinctive sonic output, etc.? I'll bet not. You probably show the kid a lot of different cats saying 'kitty' each time until it gets the idea. To put it more generally, generalizations are best made by abstraction from experience. (See also Tim (Sir Timothy) Gowers on Examples first: https://gowers.wordpress.com/2007/10/19/my-favourite-pedagogical-principle-examples-first/ https://gowers.wordpress.com/2007/10/19/my-favourite-pedagog... and https://gowers.wordpress.com/2007/10/24/examples-first-ii/ https://gowers.wordpress.com/2007/10/24/examples-first-ii/) (I frankly think this applies to the accursed phenomenon of monad tutorials in Haskell too (https://stackoverflow.com/questions/3261729/monad-in-non-programming-terms/3261837#3261837 https://stackoverflow.com/questions/3261729/monad-in-non-pro...), but some disagree.)

hood_syntax 8y ago
Along the lines of show, don't tell, the best one I've found is http://mightybyte.github.io/monad-challenges/ http://mightybyte.github.io/monad-challenges/ It helped me grok monads after I had a hazy understanding of them for a while.
theoh 8y ago
The idea of teaching using extensional definitions (an expanding list of examples) is fine, but I came across a weird case of it at a bicycle repair workshop a few years ago. It's a bizarre example, but it went like this. Audience: what's a fixed gear bike? Repair guy: it's uh, it's like a unicycle, for example... In that scenario an intensional definition is really the way to go. I don't understand how that bicycle repair guys mind worked at all.
- deleted 8y ago
  [deleted]
- kqr 8y ago
  Having ridden both fixies and unicycles, the example makes total sense. "It's like a pennyfarthing" works too. The issue is that examples are meant to leverage the recipients intuition. Very few people have intuition for unicycles and pennyfarthings, so the examples fall flat. That said, "It's like a children's unicycle" would probably count as a valid example too, and refers to something people may have intuition for. But it may also stress the wrong parts of the example. We want to convey the sense of direct drive, not circus prop.
  - lloydde 8y ago
    > That said, "It's like a children's unicycle" Tricycle? Or I’m very interested in a culture where children’s unicycles are a common thing.
    - kqr 8y ago
      Yes, tricycle, of course. If anyone figures out where this children's unicycle culture is I may want to move there.

cannam 8y ago

I recall "minimalism" in documentation being a theme during the 1990s, which I believe was influential in the design of documentation for Windows 95. I'd be interested in hearing more if anyone here knows about this. The origin text for this I believe was "The Nurnberg Funnel" by John M Carroll (https://mitpress.mit.edu/books/nurnberg-funnel https://mitpress.mit.edu/books/nurnberg-funnel) -- but I haven't read it. I have read a book of essays following up on it, "Minimalism Beyond the Nurnberg Funnel" https://mitpress.mit.edu/books/minimalism-beyond-nurnberg-funnel https://mitpress.mit.edu/books/minimalism-beyond-nurnberg-fu..., which I found quite inspiring. Both of the examples used here are older than that, which is also intriguing.

kaycebasques 8y ago
It's still one of the core technical writer philosophies. I have Minimalism Beyond The Nurnberg Funnel on my desk.
- kqr 8y ago
  Interesting references. Thank you both!

cup-of-tea 8y ago

> Babies learn a language by hearing you talk. Babies take at least ten to fifteen years to become truly proficient with a language and that includes a lot of formal learning. Once a first language has been acquired the process of learning becomes much easier. Examples are very good, though. The Python documentation is usually very good at this. Examples often lead the sections with the exact details following.

mediocrejoker 8y ago
I think that's a pretty high bar to say someone is proficient with a language. Children as young as 1-2 can effectively communicate their thoughts and feelings with others. I would speculate there are many functional adults with language skills not much better than a typical 10-15 year old.
mcguire 8y ago
http://www.healthofchildren.com/L/Language-Development.html http://www.healthofchildren.com/L/Language-Development.html

e12e 8y ago

"The part of your body that plays tennis doesn't understand English. " to quote Alan Kay paraphrasing Timothy Gallwey ("The Inner Game of Tennis"). I don't think all explanation is redundant and counter-productive, but a lot of it is. I think it is useful to demonstrate how and explain why. If a stufmdent can internalize the correct motivation of why that can help choose which skill or technique to apply.