1. 48
    1. 26

      One time I took my dog to a new vet. The vet talked to my dog like a patient. He talked to me like a dog. The vet used the words “tum-tum” and “owie” in response to my questions. I was probably 28 at the time.

      1. 26

        I hate people who dogsplain to me.

        1. 1

          Is this like the voice they use for dogs and babies alike?

    2. 16

      Figuring out what you can leave out of an explanation without lying (well, misstating) is…hard. You can avoid listing every exception to something but acknowledge they exist with “normally”, “tends to”, “can be”, etc. You can say things happen without every how or why (“GC finds memory no longer in use” is true just incomplete). You can give an example not the general principle. You can always say less than you’re thinking, and if you’re still pointing the reader in the right direction they might fill it in.

      And you can always take shortcuts at first, then go back and add reasons, exceptions, or whatever.

      Out of programming stuff I’ve read The Rust Programming Language is on its own level: it does not assume an experienced programmer and it’s trying to get you started with traits, ownership, etc. in relatively little space. Tons of examples, generally with the goal described above the code, a piece-by-piece explanation of its semantics below, sometimes with incorrect code you might write on the way there (often to show why we want the new feature in this section). It’s worth looking at just for how it’s written.

      In their own totally different way, Go’s spec, package docs, etc. are also alright at saying only what they need to. They’re reference material not intros and assume more programming vocab etc. than TRPL, but compared to a lot of docs I’ve read (or, uh, sometimes written) they aren’t too verbose and the amount of cross-reference chasing you have to do to understand stuff is tolerable.

      1. 3

        I find it fascinating that the Go spec can actually work as a reference. Usually specs are only useful to implementors.

        1. 1

          I’ve heard some folks say it isn’t quite as detailed as a spec really meant to allow multiple independent implementations tends to be. Probably even more true of things like the memory model. There were/are some outside projects compiling Go (gccgo, llgo, tinygo); I wonder if the spec was mostly sufficient for the authors, or if they often had to look up what the Go project’s compiler does or puzzle out how code in the wild was depending on unspecified behavior.

    3. 5

      Albert Einstein’s Theory of Relativity — In Words of Four Letters or Less ⌘ https://www.muppetlabs.com/~breadbox/txt/al.html

      1. 2

        That is awesome. I don’t know how understandable it would be to someone without background knowledge in physics. But very impressive how much they were able to explain.

      2. 2

        That essay is very similar in philosophy to the Gödel-proof description mentioned in the article. Like Evans points out, it’s mostly written for people who already know what Gödel’s proof is. My essay has the advantage of being about Einstein’s relativity – a lot more people have a vague idea what relativity is, at least. (And of course it’s much longer than the Gödel essay. I actually started out intending it to be shorter, but I really did want to try to explain the ideas behind relativity, and so it wound up getting longer and longer.)

        1. 2

          Back in 2011 I created an ebook out of the webpages so that I could read the essay on my ereader:

          To be honest, I cannot remember how successful the conversion was.

          They weren’t meant for public consumption, but now that you’re here…

    4. 1

      I have no idea if it works, when I try that. Being a non-native speaker sometimes it’s hard enough to write correct sentences, let alone simple explanations that hit the right tone.

      [wink] I can’t English today

      totally not me, 3h ago…

      While I think my English is good enough to mostly convey what I want to say, I claim no authority on good writing, but I absolutely notice that I sometimes have to clarify things in a (heated) written discussion, being misunderstood. An ex-coworker once described my choice of words as kinda “too correct” (guess he didn’t want to say stilted), so maybe ELI-5 would be very, very hard for me. I’m not so good with synonyms.

    5. 1

      Another trick I’ve used in the past is if you can establish two different levels of explanation, with the more basic one being pitched as being “skippable” by non-novices. Authors often use footnotes in this way, for example – or sometimes in an appendix, if the background information is too big for a footnote.

      In one essay I wrote, I hit upon creating footnote-like sections for explaining basic concepts, using indented text in a smaller font, but keeping it in-line. (The essay is at http://www.muppetlabs.com/~breadbox/txt/bure.html – see the paragraph beginning “What is a hexdump utility?” for an example of this.) Not only does this work better than a traditional footnote for a web page, I appreciated that it remained physically close to the subject matter, instead of forcing the reader to find their way to a distant location and then navigate back again afterwards. Also, I think it’s worth noting that, in all probability, the experienced reader will still wind up reading the entire section – the formatting just signals to them that they are expected to already know this, and so they don’t take it as a sign that the rest of the essay will be at a similar level. The formatting sort of becomes a get-out-of-patronization-free card.

      1. 1

        Authors often use footnotes in this way, for example – or sometimes in an appendix, if the background information is too big for a footnote.

        I feel that footnotes have the opposite role. A serious or expert reader will, as you mention, never skip footnotes; but a novice might. So you can use those for asides or things that will only be relevant to someone with more background.

        Example: In one tutorial I drafted, I used similar formatting to stave off pedantic readers who might otherwise have complained about a technically incorrect—but still very useful—definition I gave.

        1. 1

          They can also be used that way as well. Typically context plus the first sentence of the footnotes makes it clear which function is being served.