March 13, 2015
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.
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.
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.
- 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.
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.
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.
You might also like
September 21, 2013
When I was training as a teacher, I gave a simple quiz with True/False (T/F) questions. The results were terrible. Worse than chance. On one question, about 20% of the class got it right.
I had asked a simple question involving a logical AND:
True or False?
A parallelogram has parallel opposite sides AND it has five sides.
Eighty percent of the class chose 'True', even though all parallelograms have four sides. The other teachers told me the question was difficult because it was a T/F question. They said they never give T/F questions because they only confuse the kids. They said I should just forget about T/F and try a different type of question. But it was my class and my time to explore teaching and I knew that this question was not that hard. Several connections became clear in my mind: using the right part of their brains, making the problem about people, and using their imaginations effectively. I wanted to give it a shot.
I planned the next class around answering True/False questions. There would be an experiment to confirm my suspicion (that the kids were using the wrong part of their brains), a lesson using an imaginative process, and then a similar quiz to see how it worked.
The next morning in class, I wrote the T/F question on the blackboard and called a student up to answer it. He read it and said 'True' (the wrong answer). I asked him "what about this part?", pointing to the false part. He was clearly confused. The part about five sides was obviously false to him. He then began looking around through the question and stopped at the first part (the true part). He pointed at it and said 'True', as if it negated the fact that the other part was false. It's hard to describe, but I was convinced that he was simply looking for something that was true to make the whole question true. And he thought that it was the right answer. My hypothesis was confirmed: he was using a visual strategy when it was not called for.
I then demonstrated an imagination process for solving True/False questions. It went like this:
When solving a True/False question, I first imagine someone standing in front of me. He says the statement from the question to me. If he is lying, the answer is False. If he is telling the truth, the answer is True.
I asked a couple of people to carry out the process while narrating it to me. They seemed to be able to do it (and they got it right). So then I gave the quiz.
The result? Correct answers went from 20% to 80%. I felt like I was finally testing their knowledge of the material and not their understanding of test-taking strategies.
How did it work? By converting the problem from a logic skill to a social skill, the students could totally bypass the need to process difficult symbolic rules. And we could solve it as a social problem by using a structured process of imagination.
True/False questions are difficult because there are so many levels of binary confusion. First, you are looking for the correct (as opposed to the incorrect) answer. Then you must determine the truth value of the whole statement, which is a function of the truth values of the sub-statements. It's just a lot of levels to keep in your head.
The imaginative process cuts through all of that and asks one question: is he lying. You are offloading the processing to the social part of your brain, which can easily do it if framed in the right way.
You might also like
April 03, 2015
Elena Machkasova's talk at Clojure/West is about using Clojure as a teaching language for novice programmers.
Background
Dr. Elena Machkasova teaches at the Univesity of Minnesota, Morris. She is working on a project called ClojureEd to teach Clojure as a teaching language to novice programmers. Read the papers to understand the background. This talk promises to be very interesting in terms of pedagogical techniques (how to teach Clojure and programming) and tooling/setup for beginners.
Homepage - GitHub
This post is one of a series called Pre-West Prep, which is also published by email. It's all about getting ready for the upcoming Clojure/West, organized by Cognitect. Conferences are ongoing conversations and explorations. Speakers discuss trends, best practices, and the future by drawing on the rich context built up in past conferences and other media.
That rich context is what Pre-West Prep is about. I want to enhance everyone's experience at the conference by surfacing that context. With just a little homework, we can be better prepared to understand and enjoy the talks and the hallway conversations.
Clojure/West is a conference organized and hosted by Cognitect. This information is in no way official. It is not sponsored by nor affiliated with Clojure/West or Cognitect. It is simply me (and helpers) curating and organizing public information about the conference.
You might also like
April 15, 2015
This interview was graciously conducted by Nola Stowe. She's a programmer, the co-founder of DevChix, and a prolific teacher. She recently ran ClojureBridge Austin. Please shout out to her and say thanks!
Introduction
Elena Machkasova is the next interview participant. She is giving a talk at Clojure/West about adapting clojure to the classroom. The background to her talk is available, if you like.
Interview with Elena Machkasova
Nola: How did you first learn Clojure?
Elena: One of my students mentioned Clojure to me in 2009. It sounded really cool, so I included it in a class on functional programming for concurrency and was learning it partly in the summer before the course, and partly as the class was progressing.
Nola: What other languages are good for beginners or do you think clojure is the best?
Elena: To alleviate possible confusion: I don't actually teach Clojure in a beginner-level class because there are currently no tools that would make this experience smooth for new students. I've taught Clojure as a part of a couple of upper-level courses where syntax isn't that much of an issue and students are experienced enough to deal with debugging in Clojure.
Beginner CS students need to focus on concepts, develop problem solving techniques, and learn to think in an abstract, modular, data-driven way. A solution needs to be developed as a series of short, clearly defined functions). A language that supports this process without getting students distracted by unnecessary details or unpredictable behavior would be a reasonable choice. Lisp languages, including Clojure, fit into this category. We currently use Racket ( a language in the Lisp family). Python is another appropriate first language. Statically typed languages, especially object-oriented ones (Java, C++), are too complex for beginners. Languages with complex interactions with memory or their environment (C, Javascript) are not a good choice either.
Since I haven't yet tried teaching a CS1 class with Clojure, I cannot say whether Clojure is "the best" (or even a reasonable) choice for beginners, but it certainly looks promising, assuming that it is made more beginner-friendly in terms of error messages and IDEs.
Nola: What types of applications do you like to use to teach your students? (i.e., a web app, console app, todo list, recipe list etc)
Elena: So far I mostly taught Clojure at upper level and we were mostly looking into concurrency. A beginner level class is focusing on concepts, but it has to have material that students are interested in as a small project part of the course. Possibilities include data processing and interactions with graphical libraries (animation, data visualization, etc.).
Nola: What clojure libraries do you like to use when teaching clojure?
Elena: We've been looking into incorporating Quil, especially the functional mode. I've also been looking into reducers for upper level courses. Expectations is a nice testing library, definitely worth including in any level course that uses Clojure.
Nola: Why would a Mars Rover would be better programmed in clojure be better than language _ ?
Elena: Immutable data -> less possibility for error. Also, easy (i.e. less error-prone) approaches to concurrency would make large data processing fast and reliable.
Nola: Thanks for the interview. It was very informative.
This post is one of a series called Pre-West Prep, which is also published by email. It's all about getting ready for the upcoming Clojure/West, organized by Cognitect. Conferences are ongoing conversations and explorations. Speakers discuss trends, best practices, and the future by drawing on the rich context built up in past conferences and other media.
That rich context is what Pre-West Prep is about. I want to enhance everyone's experience at the conference by surfacing that context. With just a little homework, we can be better prepared to understand and enjoy the talks and the hallway conversations.
Clojure/West is a conference organized and hosted by Cognitect. This information is in no way official. It is not sponsored by nor affiliated with Clojure/West or Cognitect. It is simply me (and helpers) curating and organizing public information about the conference.
You might also like
September 11, 2013
Let's look at this logic problem:
Try to determine the answer.
Hint: It's presented visually to try to trick you (as we saw last time).
The answer is two cards, the A and the 3.
Try this one:
You are a police officer enforcing this law:
It is only legal for minors to drink non-alcoholic beverages.
You are busy, so you need to quickly assess each bar with the minimum amount of checks.
You walk into a bar, and you see this scene:
There are four people in the bar. One is a teenage boy, but you can't see his drink. One is an old man, and you can't see his drink. The third person has a coke, but he/she is behind a column so you can't see their age. The last person has a big pint of beer, but he/she is also blocked by a column.
Did you get the answer? You need to check two people. You don't need to check the old man, he's obviously not a minor. You don't need to check the person with a coke, even though he might be underage. That leaves the other two. The teenage boy on the left might have an alcoholic drink (which you can't see), and the person you can't see has a beer, so he/she might be a minor.
Was that easier? Would it surprise you if I told you that the card problem and the bar problem are equivalent? Why is it easier to solve the bar problem with almost no effort?
There are two reasons: one, it calls on years of built-up, real-world experience. Second, the problem is social--that is, it is about people. We humans are built to handle complex relationships between people. Our reasoning power is somehow magnified and clarified when phrased in terms of people in a familiar situation.
Moral: When possible present a logic problem as a problem people have no difficulty solving.
What's interesting is that you instantly know the shape of the solution when presented with the bar version of the problem. You think "I'm looking for minors and alcoholic beverages." Whereas my first reaction to the card version was "I'm looking for vowels and even numbers" (which is wrong). Only after careful, slow, deliberate thinking was I able to see that I should be looking for vowels and odds.
If you present material in the right way, it will help you teach the material better. You've likely had this experience before. Did your teacher ever do a math problem in terms of buying something and making change? Somehow, kids who score poorly in math class can still do the same problem when it's presented as a human-to-human exchange!
Social problems are not the only ones that we are hyper-capable of solving. There are also other situations that we are hardwired to understand better than symbolic puzzles. Spatial orientation (for instance, that the arm sticking out from behind the column is attached to a person) and movement are also easy to solve, and luckily some of the most interesting math problems are equivalent to orientation and motion.
By converting a symbolic problem to one that is a familiar, real-world situation, you are tapping into many different parts of the brain. The key to a good logic-to-social conversion is whether the problem solver can properly simulate the situation themselves. The bar problem is good because it's something we can all imagine.
This is one thing I try to take advantage of in my videos. Yes, you are learning Clojure to solve a very complex problem. However, the problem is familiar to most, as it involves many metaphors and simulated situations. You are teaching someone to bake. A function is like a recipe. Pure functions are like doing a calculation in your head. Side effects move you around or use up ingredients, etc. I worked hard to make it seamless to learn.
Now that we know that it's easier to learn something if we can already simulate it, the next question is how to convert math/logic problems from their symbolic form into something more suitable for whole-brain simulation. This post is long enough already, so I'll address that next time.
You might also like
March 07, 2015
Summary: Many technical books skip very important skills you need to complete a task. To avoid skipping those skills, use task analysis to break a skill into steps.
This image reminds me of so many programming language books. The first chapter introduces the syntax, the second chapter is about writing a blog. What about all the stuff in the middle? I work hard in the LispCast courses to avoid skipping these steps.
The problem is clear: most technical skills are actually made up of hundreds if not thousands of smaller skills. I mean, tons of small decisions, perceptual skills, motor skills, etc. It's amazing really what people can chunk into a single idea. There are illustrators who think of the process as two steps. Likewise, many programmers are really good and think of complex code in two steps.
Our job as teachers is as clear as the problem: break down a skill into all of the smaller skills, then teach each of the smaller skills and how they lead to the big skill. It's so easy to state, and yet most people don't do this, even when they're writing for a beginner audience.
Why do so many programming language books spend so much time on syntax but fail at the intermediate stuff? It's because syntax is easy and usually already broken down for you. Once that's covered, it's hard to know the next step to teach if you haven't done the work of discovery. But they also focus on trivial stuff, like how to type literal integers. Hello? Really? If you bang on the number keys you can make integers.
So, how do you do it? How do real teachers do it? It's actually kind of boring. The kind of boring process that you might look at and say "oh, well, obviously". The process is simply to do it yourself and keep notes about every little thing you did. Ask yourself really specific questions like "Why did I start with two circles? Why do they overlap?"
How do I make use of it in LispCast? I always start with the code I want my learners to be able to write. I write it all out first. Then I start breaking it down. Every construct (if statement, library function, etc.) is obviously something to teach. Then there are the value-add things, like why I chose one way over another. What questions do I ask myself to make the decisions? All of these things can and should be steps.
Now, the next step is matching the steps to the learners. Maybe they already know something, so I can just mention it or if it's well known, just do it without mentioning it. Some things might still be difficult, so I might need to break them down further.
At the same time, it could be better to avoid a certain concept. Like if you'd normally do it with a cond but they already know if, perhaps you should stick to what they know so you don't have to add several minutes to explain something that's not relevant to your topic. I try to go deep, so it's important to minimize the breadth of the material in order to finish on time. All of these little skills go into a curriculum, which I'll talk about in a future post.
I don't think this process is hard or original. I learned it from a book about teaching. I do think that most people who write technical books might be subject-matter experts, but they don't have any training in teaching. Teaching is a huge advantage. Even a simple process like this could really differentiate you from the other technical authors out there. And breaking down a task tells you what you need to teach (no more writer's block).
If you like the idea of teaching technical material, please sign up for my Technical Teaching mailing list, where I'll occasionally share skills for making material that helps people learn.
You might also like
September 17, 2013
I always hated in school when the teacher would instruct us to use our imaginations to solve problems. Well, hmm. Especially as a kid, my imagination was filled with magic. Not very useful. Not that you shouldn't use your imagination. You should. But as an instruction, I find it lacking. The teachers were just being lazy.
See, the thing I learned through a lot of experiments and reading is that our imagination is very powerful if you use it correctly. But much as our computers can run any possible program, our minds can imagine any situation. The key to using our imagination effectively is to learn to harness the infinite potential and direct it to a purpose.
One set of techniques I studied was called Neuro Linguistic Programming. It is thoroughly interesting, especially the earliest stuff, but avoid the cultish seminars. The early stuff was based on Cybernetics and linguistics (specifically Noam Chomsky's transformational grammar). It was quite rigorous as far as informal studies go. It has since become a new-age movement. Tread carefully if you wish to explore it.
One of the most intriguing aspects of NLP is that it teaches you to discover the structure of a mental process through introspection in terms of the raw sensory experience. That is, what do you see, hear, feel, etc. You break it down into the smallest steps that can be measured. You can then understand your own process and give yourself more control over your own apparatus. It sounds like a structured use of imagination. By deconstructing your imagination and guiding another person through the steps, you can transfer the outline of a skill to someone else.
I know this must sound like magic. But don't we expect teachers to pass skills on to others? Teachers routinely break down skills to teach them in a process known as task analysis. You are simply doing it to your imagination. It's not magic. It's not instant knowledge transfer. Practice and experience still count for a lot. But it can get you pretty far.
If it still sounds like magic, all I'm saying is that you switch from A to B:
A: Pure functions are functions that don't have any side-effects. Use your imagination.
B: To determine if a function is a pure function, look through the function line-by-line. On each line, imagine a green checkmark if the line has no side-effects. Imagine a red X if it has side-effects. When all lines have been marked, if you have any red X's, your function is not pure.
While correct, the first explanation gives very little help to your imagination. In fact, my first response to explanations of type A is to think about what it might mean. But I can use my imagination with effort. When I do that, I realize that I am imagining visually scanning the function (in my mind's eye) and marking lines with side-effects. The second one asks you to imagine just that. Asking someone to go through a process makes it clearer.
NLP does have a lot of merit, especially when it comes to teaching. Our mental processes can be introspected, analyzed, and described. And we can then guide a student through a process similar to what goes on in our heads when we solve the problem. This is the last piece I need to tell the story of one of the most successful things I have ever taught. Next time.
You might also like
September 09, 2013
Here's a problem you might see on a standardized test:
Go ahead and try to solve it. Choose an answer.
When people answer this question on a test, the most common answer is C. Yellow triangle and red square. They try to make the statement false by negating all of the colors.
This is wrong. Actually, the correct answer is A. It is the only one that makes the statement false. Why?
This is a propositional logic problem. The colors and shapes are a red herring. The rule for implication (if-then statement) is:
An implication is false if the antecedant is true and the consequent is false.
Kind of boring and therefore hard to understand if you don't already know the rule. It is unlikely that any amount of explanation will help, though you should try to understand if you don't already. Here, try this. If the triangle isn't red, then the statement doesn't apply, so it is true by irrelevance. That eliminates C and D. B obviously makes the statement true, so it must be A.
Researchers found that explanations alone do not help. I read an article about a study where similar questions were asked to a group of students. The students were hooked up to EEG (Electroencephalography) machines to measure what parts of their brains were active during each question. They also asked them to say which ones they thought they got right.
Photo credit: Petter Kallioinen
What they found was that most of the people who answered A were using their frontal and temporal lobes: the parts of the brain responsible for logic, reasoning, and language. Most of the people who answered C were using their occipital lobes, which is responsible for vision.
Moral #1: Recognize what type of problem you need to solve. If possible, use the right part of your brain for that problem.
The people who used their vision centers were doing visual pattern matching, looking for shapes and colors. This is typical of a fight-or-flight response, where you are running from a tiger and need to quickly spot it in the jungle.
Moral #2: Don't get nervous during a test. Anxiety makes some parts of your brain more active--usually the wrong ones.
In addition, the people who used their vision center to answer the question thought they got the answer right just as much as the people who actually got it right.
Moral #3: The different parts of your brain are good at different tasks. If you ask the occipital lobe to do pattern matching, it will, and it will think it did a good job--even if it is not a pattern matching task.
The second part of the study tried to teach those who got it wrong to do it better next time. They broke them into a control group and an experimental group. The control group got an explanation like the boring one above on how to make an implication false. The experimental group got the same explanation plus they were trained with a little bio-feedback to use the right part of the brain.
The result was that the control group didn't make any gains. And they still thought they got it right. The experimental group did significantly better. They scored higher and were more likely to say they got the wrong answer when they did get the wrong answer.
Moral #4: Explanation alone is basically worthless. Even practice is not enough. The key is to recognize what type of problem it is, use the right part of your brain, and don't listen to the rest of your brain. Only then is explanation useful.
Now, this is easier said than done. I don't have an EEG machine. I've never done bio-feedback. But the idea has helped me tremendously when teaching math. It is not hard to recognize when someone is using the wrong part of their brain. First, they confidently get the wrong answer. Second, they are getting the basic mechanics of the problem wrong. They're looking for something. They find the closest thing to what they want. They're done.
Logic problems aren't about looking. They're more abstract. Common helpers for doing logic problems are mouthing words, making gestures, and looking away from the problem.
Recognizing whether someone is using the right part of their brain is easy. But now you know explaining won't help. The hard part is to get them to use the correct part of the brain. That's what I'll talk about next time.
You might also like
