How To Derail Your Readers And Students

June 9, 2013 at 5:17 pm in Book, Editing, Language, Teaching, Tech, Writing

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.

You want to 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:

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

even though I might be tempted to do this:

var 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

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.

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 comment

My Writing Workflow

November 1, 2011 at 4:53 pm in Editing, Writing

Today marks the start of PragProWriMo, where the fine folks over at the Pragmatic Bookshelf are encouraging aspiring writers to write a technical book over the course of the month. Over at the forums, I shared my writing workflow, which I’m reposting here.

My process may not be a good fit for everyone, but it’s served me quite well.

I usually map out my idea using either OmniOutliner or the free online CheckVist app. I used to use mindmaps but I found them just a little too distracting. CheckVist can export OPML formats which you can bring into a mindmapping software or even convert to HTML or Docbook markup if you want.

Once I have my thoughts down I start narrowing down my focus a bit. I think about my audience and think specifically about someone I know who would benefit from this book. It might be the designer who needs just a little help with jQuery, or it might be the Java programmer with years of experience that wants to pick up Ruby. But I’m pretty specific, and I found that the best approach really is to target one specific type of reader, rather than to try to be all things to everyone. That said, you do need to make that abundantly clear to the prospective reader.

Once I’ve gotten a topic and a target audience, I start filling in the blanks in my outline with some good “introductory” text for each node in my outline. If I can’t think of an elevator pitch for each one, I either decide if I need to learn it, and mark it as research, or I evaluate if it’s really in scope for my reader and target audience. Sometimes things we want to teach aren’t what our readers need to know right now.

Andy Hunt’s Pragmatic Thinking and Learningis a great book, and it has a chapter that explores the Dreyfus Model of Skills Acquisition. This model has stages people progress through when learning anything new. I’ve found that the best books take people from one of these stages to the next. I try to do that with my writing.

So, now that I have my topic, target audience, and a good idea about what I’m writing, I start writing. I write about whatever interests me first, which means I may have three or four chapters going at a time. I try to write EVERY day. Even just for a little bit, because having to miss one day of writing due to a kid’s sports game is better than not writing all week, trying to cram it all in on Saturday, only to be hit with having to go to a kid’s sports game. If you do that, you’re now a week behind.

Once I’ve got a chapter completed, I export it to a PDF on my iPad to do some reviewing and editing. This is also where I PHYSICALLY CHANGE LOCATIONS. Using a different medium and a different location puts me in a separate mindset. It seems like a silly trick, but it works. B

When I’m writing books that have source code, I use a Git repository with a branch for each version. I’ll use 0001_start and 00025_refactoring or things like that so they’re sequential. I can then export each branch to a directory structure so I have code my readers can download. This also makes it easier if I discover that I left an important step out in earlier code – I can simply commit and rebase or cherry-pick it through to the later versions.

I tend to write my code at night and my prose during the day. And I tend to write code first and write the prose around it. I’m a better coder at night, it seems.

Once I have a few chapters, I start looking at introductions and conclusions. I usually don’t even try to write these until I have a few chapters because I don’t really see how things fit until that point.

I can average a 20 page chapter every two weeks, and sometimes faster. But you have to keep in mind that faster is better. For more perspective, a 10 chapter book would now take me 20 weeks, or close to six months! So it all comes back to making the time to make this happen, writing every day.

As for what I use for writing, I do everything in either Vim or TextMate, and I use DocBook, which is an XML markup. It’s something I picked up in 2006 and can’t live without, but it’s not for everyone. It’s more important to write good stuff than it is to fixate on tools or process. You’ll find those things will distract you too much if you let them.

So that’s my process. If you have questions, feel free to ask away.

No comments

Slight Change of Course

August 10, 2010 at 10:38 am in Book, Editing, Personal, Writing

This week I start my new part-time job as a Development Editor at the Pragmatic Bookshelf, the publisher I’ve worked with on my last two books. They’re wonderful people, and I’m honored to have the chance to work with them to help authors bring their books to completion.

For those unfamiliar, a Development Editor works with an author to help guide the book’s progress. It’s part content editor, and part project manager. I’ll be reviewing chapters, making suggestions on content, ensuring that things are clear, easy to follow, and are written in the appropriate “house style”, but I’ll also help set short and longterm goals for the book’s progress. I’ll manage the technical reviews and help the book along in the production process. Best of all, I’ll be able to share what I know about book writing with other aspiring authors. It’s all very exciting, and it goes hand-in-hand with my love for teaching and mentoring people. I won’t be responsible for copy-editing the book though. Spelling and grammar corrections happen at the end of the process and the Pragmatic Bookshelf has an absolutely amazing copy editor who makes everyones book better.)

I’ll be starting off with one book, and picking up a second very soon. I have no idea what this means for my consulting business long-term, but after 15 years of coding for money, I’m excited for a change. I’m extremely grateful to Dave, Andy, and Susannah for giving me this opportunity.