How To Derail Your Readers And Students

There’s no shortage of software developers who are eager to share their passion with others through writing and teaching. It’s an amazing time, and it’s great to have all these resources out there for us to all get better at what we do.

If you’re a software developer who wants to teach others how to do things, listen up, because there’s a chance you’re derailing your students and undermining their confidence before they even get started. In this article I’m going to point out some real quotes and statements I’ve seen that hurt, more than help, the student. And I’m speaking from experience, having done a really good job derailing readers and students by doing these things myself. I’m sharing what doesn’t work, and what does work, in my own experience. I believe that this advice applies not only to people who teach programming, but also to people who write books, articles, and screencasts about programming. By avoiding these things, you’ll create better learning experiences.

#1: Saying “This is really hard.”

If you start off with this one, you’ve already lost people. You’ve demotivated all but the smartest, advanced student. Students want to know they will be successful. Thy need reinforcement from you. They need to know that you’ll guide them through the things that are hard.

Tell them that many people struggle, or that the path will be difficult, but far from impossible. Show them what they’ll be able to accomplish when they’re done. If you’re teaching object-oriented programming, show a before and after example at the beginning of the lesson. Show them the spaghetti code, then show them how much cleaner it will be. Don’t worry about whether or not they’ll “get” what you’re showing. If you take the time to plan what you are showing, your simple example will make sense.

#2: Saying “This is really simple.”

On the other hand, if you tell the students something is simple, you run the risk of derailing novice students who run into errors they caused by themselves. In programming, nothing is simple. A small typo can cause all sorts of trouble for the inexperienced, and then their confidence is undermined. “But she said it would be simple! What am I doing wrong?” And then the learning stops.

Avoid “easy,” “simple,” and similar words for this reason. You can certainly tell the student that the concept you’re introducing is basic, or introductory, or “the first step.” But keep in mind that everyone starts at a different level. Something as “simple” as declaring a variable has a lot more going on.

#3: Saying “Don’t worry about this right now, we’ll talk about it later.”

This is almost always a sign of impatience on the part of the teacher or author. You want to get to the good stuff, but you’re stuck in some kind of “chicken and egg” situation, so you show something advanced, and promise to explain it to the student later. The problem is that we don’t know when that will be. Be specific. Say “We’ll cover this in a few weeks” or “We’ll get into this topic in detail in chapter 14.”

But more importantly, ask yourself if now is the time to show this to your students. Is there a more simple way you can do something, even if it’s not the “right” way? If you don’t have time to explain the “why”, what is the benefit of introducing the concept at all?

#4: Saying “Don’t worry about this right now, you’ll get it eventually.”

This is similar to the previous one, but it’s a little more problematic because it’s putting the effort entirely on the student to figure it out. Instead, tell the student that they’ll get a lot more practice with the concept. Again, make it clear at the beginning why you’re introducing the concept and how they’ll benefit.

#5: Not Having A Plan

If you’re composing a chapter or a lesson and you don’t have the end in mind before you start, you’re going to be all over the map and your students or readers will be confused. If you’re doing a tutorial, write all the code first, then break it apart, break it down, and explain it. Don’t just write words and throw code samples in. That’s not a tutorial. That’s a reference guide and there’s a big difference. There’s a big difference.

Students need to know the plan at the beginning. They need to know where they’re going and what they’ll be able to do at the end. If you don’t have that plan, how can you convey it to them?

Use mindmapping, use outlines, use some technique that lets you easily figure out what your grand plan is. If you can, start with a “competency-based” approach:

1. Figure out what you want them to be able to do
2. Come up with how you will evaluate that they can do it (a test, a project, etc)
3. Come up with the exercises you’ll have them practice so they can eventually do #2
4. Fill in the explanations.

This is what’s called “performance based learning” and it’s really effective, but it has to be planned out. Trust me on this – it works so much better than winging it. I’ve done both, and I will always have a plan now, and it will always be based on this order.

#6: Not writing code at the students’ level

If you’re an experienced programmer, and you’ve been through lots of code reviews, you’ve probably developed a style of coding that’s clean, compact, and free of duplication. But if you’re teaching someone how to do something in your language, being terse is going to freak a lot of students out.

When I’m writing examples, I tend to break things into as many statements as I need based on the audience at hand. If I’m writing a book on “Beginning CSS”, I’m not going to write code like this:

  border: 1px solid #000;

I’ll write it like this.

  border-style: solid;
  border-width: 1px;
  border-color: #000000;

That is, I’m going to spell out each property, and then I’ll show the condensed version if it makes sense:

If I’m teaching JavaScript, I think this approach is better:

let age;
age = prompt("What is your age?");
age = parseInt(age);

even though I might be tempted to do this:

const age = parseInt(prompt("What is your age?"));

When you’re teaching, you need to explain the meaning of things. I know when the long version is appropriate, and I also know when the short version is appropriate. The students don’t, and it’s my job to get them there.

Silence the voice of your peers that will tell you to refactor your code  Production code is not learning code. Show the cleaned up version later and ask thought-provoking questions about the differences.

#7: Having out of context, incomplete, irrelevant, or broken examples

Your examples need to work and they need to have context. While some students do just fine with an array defined like this:

array = ["a", "b", "c", "d"];

Many others don’t. There are many ways that people learn. 1 Try to adapt a bit and use examples in context:

const names = ["Ted", "Barney", "Marshall", "Lily", "Robin"];

In addition, make sure the code works. Make sure it’s free from syntax errors, and make sure it’s reproducible given the steps you wrote. Nothing frustrates a reader more than trying o follow directions with steps missing. It’s really hard to write tutorials that people can follow. It involves a lot more work than doing it once and writing the steps down.

It’s easy to be teacher-focused and say “Well, they’ll learn from figuring it out.” They’ll learn, alright; they’ll learn that you don’t care about them learning what you’re teaching.

Treat example code like production code; use proper variable names, write it cleanly, and test it every so often. Test not only your code, but the process you’re using to teach it. If the new Android SDK comes out and the new project generators break things, you need to have that in your tutorial too.

#8. Flying Solo

If you’re writing a book, you need an editor. Maybe you don’t need a publisher, but if you’re going it alone you still need a development editor who can look at what you’re doing and help you find the holes. You also need to have your content peer-reviewed. Get feedback from experts, get feedback from readers, get feedback wherever you can get it. You will get better results.Every single person who creates learning material can improve, no matter how long they’ve been at it.

Wrapping Up

The last thing to think about is your conclusion. Don’t just throw a last bit of code out there and jump to the next topic. Recap the concept you’re covering and give the reader or st8dejt t9ke t0 reflect. Metacognition (thinking about thinking) is pretty powerful stuff, and a good closing really helps things stick.

So, all of these things, from avoiding dangerous words, to planning, feedback, and a strong closing, are the things I look for in my own writing, in my own class preparation, and in the writing and course design of others I provide feedback on.

Take some time and reflect on these things. Which of these do you do in your current writing or teaching? What ways can you do better?

Finally, take a look at this passage from an online tutorial about Objective-C:

Pointers can cause a lot of confusion with newcomers to programming or just newcomers to C. It is also not immediately clear to some people how they are useful, but you?ll gradually learn this over time. So, what is a pointer?

[… example omitted….]

Clear as mud? Don’t sweat it. Pointers are hard – often considered the hardest thing to learn when picking up the C language. Pointers will eventually become second nature to you though, and there will be more on pointers within Objective-C further in this series.

I’m not linking to this tutorial because I don’t want to pick on it too much, but this is one in at least 10 articles and books that I’ve read that bring up this topic of pinters in the first chapter. After reading that, what problems do you see here that could derail a beginner? Are you motivated to keep going? How do you feel after reading that?

Got any other things you think I missed? I’m always interested in improving my own writing and teaching.

1 http://epltt.coe.uga.edu/index.php?title=Multiple_Intelligences_and_Learning_Styles#The_Eight_Intelligences