How to avoid "Makes sense if you already understand it."

Summary: Most technical writing is obtuse unless you already know the topic. Focus on the learner and their skills and it will clarify your writing.

Why is most technical material completely undecipherable unless you already understand it?

Oh, the joys of learning about monads:

All told, a monad in X is just a monoid in the category of endofunctors of X, with product × replaced by composition of endofunctors and unit set by the identity endofunctor.^1

All jokes aside, this is typical of technical writing. Why is it so obtuse? I'm sure there are some people who could read this and confidently nod their heads. But to the rest of us, it's completely obtuse.

But obtuse language is not limited to mathematical texts. Here is an excerpt from a section of a Clojure book introducing integers in Clojure:

Integers comprise the entire number set, both positive and negative. Any number starting with an optional sign or digit followed exclusively by digits is considered and stored as some form of integer, although several different concrete types are used depending on the circumstance. Integers in Clojure can theoretically take an infinitely large value, but in practice the size is limited by the memory available.^2

I program in Clojure every day. I probably write integers in Clojure every day. Yet I still have to reread this paragraph to make sure I understand it. Yes, it makes sense to me, since I already know the material. But this paragraph does not teach. It simply records technical facts. A new Clojure programmer would gain just as much from this as from the monad explanation above.

I don't mean to pick on any books in particular. This is pervasive in technical books from all fields. It's why most learners consider themselves self-learners. They did the hard work of reading and rereading this dense, obtuse, and unhelpful material, and rightfully feel that the bulk of the effort was on their end, not the author's. When they finally get it, they don't credit the author. They credit their own perseverance.

Is this fair? You do all the work of writing the book. How can you get the credit?

The answer is surprisingly simple. You should focus on skills, not technical knowledge. Reread the integer paragraph above. Notice that it's all about facts. Where does the reader fit in? What does the reader do with this knowledge? Why should the reader care? All of that is absent.

Without answering these questions, the paragraph is most generously described as reference material. It might contain knowledge you will one day need. It will sit on your shelf until you have an actual question to answer, then you'll look it up. And you'll feel like a self-learner. But it's not teaching you.

It's like a clock. When you need to know the time, you can read it. But it can't tell you why you should care that it's 11:14pm.

How do you focus on skills? Think of the poor reader! Ask yourself: what do they do in their real life? Let's go through the integer paragraph and convert it into skills. We're trying to convert the fact into something they might want to do with it.

Before I do that, though, let me say this: these are my interpretations of possible skills. Not all of these are totally relevant. I didn't write the paragraph, I'm just interpreting it. So a lot of it might seem pedantic or unimportant.

• Skill: If you want to make a positive integer, type only digits.
• Skill: If you want to make a negative integer, put a - in front of digits.
• Skill: If you want to emphasize that an integer is positive, put a + in front of digits.
• Skill: When you're at a party and you want to impress your Clojure friends, you can mention that Clojure represents integers with several concrete types.^3
• Skill: If you want to make really big integers, you can.
• Skill: If you see an OutOfMemory error, check that you are not making an integer that is too big.^4

It's good to break text down like this. Often it shows what skills are important and what should be saved for later (so late, sometimes, that they fall off the end of the book!). As the teacher, your job is to choose what they skills they need to learn.

Notice that this begins to look like a task analysis. Each of these skills should be broken down as far as they need to go for your audience. These raw skills that I wrote above are useful like this as part of the process, but they need to be refined a lot. That's the goal of making a curriculum, which is another post.^5

Conclusion

Here's the hard truth: writing down facts is the easy part. It's what lazy authors do. There are thousands of technical books out there written by people that do no more than document someone's (sometimes impressive) knowledge. Teaching is hard, but not impossible. It will set you apart.

Learning is about skills. Even what seem like plain facts have a reason for existing. People want to do something with them. The difference between writing and teaching is that teaching focuses on the learner and their skills, whereas mere writing is just about the topic.

If you like the idea of teaching technical material (not just writing about it), please sign up for my Technical Teaching mailing list, where I'll occasionally share skills for making material that helps people learn.

1. From Categories for the Working Mathematician by Saunders Mac Lane, page 138.

2. From The Joy of Clojure, Second Edition, by Michael Fogus and Chris Houser, page 27.

3. Can you think of a better reason for mentioning this? Who needs this knowledge, and for what? It becomes clear in subsequent paragraphs.

4. Can you come up with a better reason to men tion this?

5. Just for reference, I think this paragraph touches on the following skills:

   • Write positive and negative integers.
   • Read positive and negative integers.
   • List the concrete types that may represent an integer.
   • Recall that larger integers may take more space than smaller integers.