Sometimes the hardest part of an explanation is knowing where to start. For example, I’ve spent a lot of my career teaching programmers who are familiar with one programming language, frequently Java, a new programming language, maybe Ruby or Clojure.

The challenge in teaching programming languages is that even a moderately successful programming language is sprawling technical and social artifact: At its core, every programming language has the code that translates the programmer’s instructions into instructions that a CPU can act on. But if the language is at all popular you will also have a rich ecosystem of utilities and tools. And around that you will have a community of programmers who, over time, will come up with sometimes conflicting best practices.

So now imagine you are standing in the front of a room full of people who are looking to you to introduce them to all of this. Where do you start?

Start With a Lie!

I generally start by lying my butt off. For example, when I’m introducing the Clojure programming language, early on we will start seeing things in our programs that look like this:

[1 2 3 4]

Ask just about any programmer from any language background what that is and they will say That’s an array.

Unfortunately the Clojure thing above is not really an array. Yes, it does represent an ordered collection of (in this case four) items. Yes, you can easily find out how many items there are — just call the count function. And yes, you can index into it with an integer and get the second or the fourth element very quickly. But unlike a traditional array, which is backed by a continuous block of mutable memory, a Clojure vector — to give these values their proper name — is a sophisticated immutable data structure organized more like a tree than a block of memory.

That’s all true, but when I’m just starting out with a group of neophyte Clojure programmers, I say This thing with the square brackets is called a vector. For now you can think of it as an array. And then I move on.

But didn’t I just say it wasn’t an array? I did, but it doesn’t matter: When you are trying to get an explanation off the ground it’s OK to start with a simplified version of reality. The idea is that you kick things off with the cartoon version of reality and later, after your listener has a bit more context and is feeling more comfortable with the subject you can circle back and fill out the picture.

You can think of this approach as the successive approximation explaining technique. You start with a rough sketch of real life: It’s an array. Then you move on to the next topic, possibly simplifying that as well. You keep doing that until you have gotten across a cartoon version of the whole topic. Once you done that you go back and start filling in the details, correcting the lies to a listener who is now prepared to understand the nuances.

So with Clojure I start by saying Vectors are (more or less) arrays. Then I go on to the other Clojure data structures and then to how all of the Clojure data structures are immutable but can make very fast, modified copies of themselves. And then I circle back to why that thing with the square brackets is different — and more — than a simple array.

Progressive Idea Loading

These kinds of Start Simple explanations are something like the progressively loading images that you see on web pages, the ones that initially get downloaded as blurry blobs and then are slowly refined into the full resolution image — Typically of a cute cat. You start with a blurry but digestible explanation and once that is in place you start refining it.

The trick to pulling off the Start Simple plan is to come up with a cartoon version of your subject that is both internally consistent and within striking distance of what your listener already knows.

Thus when I kick off an explanation of Clojure I generally start by presenting it as a conventional programming language, which it is emphatically not. But I plow ahead, talking about how you name things, how you define functions and organize how your code into files. Along the way I say Oh those vector thing, they’re sort of arrays. Once my listener has the general lay of the Clojure land I go back and start pointing out the things that makes Clojure an unconventional programming language — the syntax, the focus on functions and most of all the immutable data structures. Which brings us right back to the reason vectors are not really arrays, at which point I’m hoping that my listener has enough grounding in the basics to understand the next level of detail.

Beware the Angry Expert

If you do employ the explanation by successive approximation technique sooner or later you will run into an outraged expert. like this: You are happily telling your listener that this [1 2 3 4] is, more or less, and array. And a person expert in the field — in this case Clojure — will over hear you and bellow:



The thing to do in these situations is to smile stupidly, thank the expert for his or her input and go right back to saying more or less an array.

The world is full of people who are expert in X but have no idea how to explain X. The trouble with experts is that they have a tendency to try to explain everything at once. But if you try to explain everything at once you are likely to end up explaining nothing at all, permanently. So smile and ignore the experts, at least to the point of not trying to get every detail accurate up front.

Wrapping Up

So there you have another explaining plan: Start by explains a simple, cartoon version of the real world, just enough to ground your listener in the subject. To put it bluntly, you lie. Just a little. Then roll back and start filling in the details, untelling the lies one by one.

 — Russ