Thank You For Playing

Amateur game design for the technically impaired

Writing effective tutorials for beginners

with 2 comments

This may seem that it is aimed at the complete opposite end of the spectrum: those who are expert enough developers to write their own guides to coding. And it is. I wish I could come up with an exhaustive list of great ways to recognize a good tutorial, but I recently took on a pretty weighty endeavor and the very lack of good resources is what triggered my desire to express myself.

dev1.jpg


The weighty endeavor I speak of? I decided a couple days ago to try and learn as much of the C++ language as I could from online tutorials. I haven’t given up completely, but it seems that I’ll need a face-to-face tutor to help me put it all together. I’ll allow that coding isn’t easy, and that having a teacher (or friend in my case) is perhaps paramount in being able to learn a language in any effective manner. However, the sort of problems I ran into with online tutorials were so inexcusable and so rampant that I can hardly imagine how the writers could conceive of passing their material off to beginners. Most of these tutorials claimed they would be very useful to those with no coding experience at all. Hogwash.

I did learn a little C++ in the process, and with that I am able to go back and criticize some errors in these guides. And where I became unable to continue, my criticism is simply that. Here is my list of awful mistakes in C++ “beginner” tutorials:

Don’t recommend useless tools to me

If you’ve ever taken a stab at C++ you’ll know that you can code and code and code, but you’ll never get anything out of it (and never see if you were doing it correctly) if you don’t have a compiler. First off, it’d be nice to see one of these tutorials give a good introduction on the compiler, in idiot terms, and recommend one for beginners. Pretty much all of the tutorials I read gave me a technical explanation of the compiler and recommended several which I found completely useless. If you are a beginner, do not waste your time with a command line compiler. It is too complicated. You’ll never get around to coding because you’ll spend hours trying to figure out how to compile your first program. Furthermore, if the tutorial gave you a program that has incorrect code (you’ll see some of this later), you’ll never know if the error is in your compiling commands or in your code. I spent a good while trying to get Borland to work because it seemed to be some sort of standard. The only compiler I came across that I would ever even bother mentioning to a beginner is Bloodshed Dev-C++. And I’ll explain what tutorials left out: you open this program, type or paste some code directly into a text box, use the Compile command (which is as easy as finding it in a regular old Windows program menu) and then run it, another click through the menu. Dev-C++ will run only from the last time that you compiled, so if you change the code but don’t compile it, it won’t change the way your program looks when you run it.

A tutorial from http://www.cprogramming.com/ said:
There are several common compilers: in particular, Borland C++, Microsoft C++, and GNU C++. There are also many front-end environments for the different compilers–the most common is Dev-C++ around GNU’s G++ compiler.

It did have a whole separate page that explained the compilers better, but a tutorial should include all of the necessary information for its reader. And this particular one should’ve omitted all of those other compilers besides Dev-C++, the one it mentioned last. All those other ones are not for beginners. Some other tutorials didn’t bother explaining or suggesting compilers at all.

Take me step by step

This is perhaps the very definition of what a tutorial is. Most of what I came across would have a section which described an aspect of coding, and then move on to another section which was presumably the next step in the process. I did not get the feel however that I was learning something on top of what I had just learned, rather I felt like I was learning something entirely new. “I showed you how to define and manipulate variables, now let’s move on to loops.” A good tutorial will start explaining loops by showing me all of the ways I can use loops (my new tool) to affect variables (the thing that I might just be starting to understand). To be fair, this was not a big problem in the tutorials I read. What I should really suggest is that the writers slow down and take the time to explain their new concepts from different angles. After all, their guide is supposed to be for a beginner, right?

Tell me what it means

The first program I write, I’ll be honest, I don’t care what the code means. When I pasted that code into Dev, compiled and ran it, I was just excited to see that I could actually do something. But after I saw it (My program was just a line of text that said “Hello world!”) and slowly began to understand what all those keywords were doing, I found it very frustrating when the tutorial would introduce something new without explaining it. The biggest problem I had with this was the introduction of the endl keyword. I put it in and noticed that it made the program skip to the next line, but I remember thinking “Didn’t I use ‘n’ to do that before? What’s the difference?” For my purposes, there is no difference. Thanks for explaining.

Cut the intellectual/technical/formal garbage

Many tutorials gave sufficiently simple enough explanations for one or two pages. But then I would get this:

From http://www.cprogramming.com/tutorial/lesson4.html:

arg_type just means the type for each argument — for instance, an int, a float, or a char. It’s exactly the same thing as what you would put if you were declaring a variable.

There can be more than one argument passed to a function or none at all (where the parentheses are empty), and it does not have to return a value. Functions that do not return values have a return type of void.

This page of the tutorial is supposed to be explaining functions, and I suppose the writer didn’t realize I still haven’t learned what an argument does in the context of programming. Here’s more technical stuff that should’ve been explained in idiot terms:

From http://www.cprogramming.com/tutorial/lesson3.html:

WHILE – WHILE loops are very simple. The basic structure is

while ( condition ) { Code to execute while the condition is true } The true represents a boolean expression which could be x == 1 or while ( x != 7 ) (x does not equal 7). It can be any combination of boolean statements that are legal. Even, (while x ==5 || v == 7) which says execute the code while x equals five or while v equals 7. Notice that a while loop is the same as a for loop without the initialization and update sections. However, an empty condition is not legal for a while loop as it is with a for loop.

While loops are very simple? Also, I never got a good explanation of Boolean. From any tutorial.

Tell me what I’ll be able to do

None of these tutorials did this. At the beginning of a section, tell me “By the end of this section of the tutorial, you will be able to write a program that will bring up words on the screen.” They’ll start by showing you the program that says “Hello world!” and then explain how the program works. And if the writer is confident enough in his tutorial, maybe he could even give you a project. “Now you try! Write a program that will simply say ‘This is my very own program’.” If they gave you the tools, you should be able to do it. And if you can’t do it, you know you aren’t ready to move on.

Show me examples of the right way

Every tutorial I read gave me one example for every concept it introduced. I want something more like four examples. Come on guys, this stuff is easy for you. Don’t bother writing a guide if I’m going to be limited mostly to inputting your code verbatim.

Show me examples of the wrong way!

“Hey, you explained the ‘for’ loop to me, and I tried doing something with it besides the exact same thing that you did. What did I do wrong? Oh nice, you have an example of a common mistake that looks a lot like what I did. Now I know what I can do to fix it.”

Yeah, there is maybe a little of this, but none of the examples are very useful.

Don’t give me code that won’t work

A tutorial from http://www.planet-source-code.com gave me this code:

#include <iostream.h>
 int main()
 {
 cout << "Hello World!" << endl;
 return 0;
 }

This guy said straight out of the bag that he uses Dev-C++, so I remember thinking “awesome, that’s the one I decided was worth my time. Maybe this tutorial will be worth my time.” Wrong. Put that code into Dev-C++. It doesn’t work. Keep in mind this is the very first thing he has you do. Because I learned a little of the language before finding this tutorial, I know what’s wrong with the code. Why doesn’t he? Perhaps this is an old tutorial and he doesn’t have the same version of Dev that I have? Getting rid of that .h after iostream would give you a program that would run (.h is an extension used in C apparently? Dude must’ve gotten confused).

Similarly, here’s some code I got from http://www.codepedia.com/1/CPP-Beginners-Tutorial that doesn’t work:

1. include <stdio.h>
int main()
 {
 printf("Hello Worldn");
 return 0;

Turns out this would work in C but not C++. Then why is it in your tutorial for beginners?

Also, a lot of the “first program” codes I found in these tutorials left out a command that seemed pretty important to me. Leaving out the “cin.get()” command at the end will make it so that the program will run but immediately close, and you, the novice programmer, will think “what the hell did I do wrong? I put it in exactly as he said!” Only one tutorial included the “cin.get()” command, which leaves the window open until you press enter, so you can actually see what your program looks like.

The best and worst

You’ll notice I mentioned the Cprogramming.com tutorial a few times, but it wasn’t the worst. The reason I was able to mention it so much is that it was good enough for me to bother with it for a while. I am also still trying to learn from one I didn’t mention which is available at http://www.cplusplus.com/doc/tutorial/introduction.html. It isn’t without its flaws, the writing is too technical in a lot of cases. The two that I consider the worst have got to be those which provided a “my first program” that didn’t work. We’re talking about the simplest uses for the code. If you can’t get that right, I’m not going to keep reading. Those were http://www.codepedia.com/1/CPP-Beginners-Tutorial and http://www.planet-source-code.com/.

Sadly

It seems that you just can’t learn this particular language from tutorials alone. Maybe I’ll take out a book from the public library. But I feel very strongly that it’s not the difficulty of the language which is limiting me. Perhaps at some point it would be too hard to explain in a tutorial, but this early on? It’s just that the resources are so poorly presented. Not that I need to know how to write in C++, but I hate to be promised an island and then have a mound of dirt handed to me.

Advertisements

Written by ericharm

February 29, 2008 at 10:16 pm

2 Responses

Subscribe to comments with RSS.

  1. I also found myself with some time and wanted to learn c++. I found that I had exactly the same experience as you did. I am still busy, but if I didn’t have as much time on my hands as I do, I don’t think I would be able to do it. I have enjoyed working with wikiversity.org, but it is also not perfect. Some things I have had to look through forums and watch youtube videos to understand. I am gradually getting it together, but it is slow.

    Vernon

    November 18, 2008 at 2:57 pm

  2. I forgot to mention, it’s because of all the searching that I found your site. Can’t remember what I was looking for now?

    Vernon

    November 18, 2008 at 2:59 pm


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: