On the art of writing programming tutorials

Richard Kenneth Eng on 2017-06-09

I recently published a Smalltalk programming tutorial. It has garnered some criticism for being too difficult for rank beginners. This compelled me to give my philosophy for how to teach people programming…

There are basically two kinds of beginners:

  1. People who are so intimidated by programming and lacking any kind of technical aptitude that they need a great deal of hand-holding.
  2. People who are not afraid to explore and play and wade into the technical waters where there be monsters!

I’ve seen both kinds of novices. For the first category, I think starting with any conventional programming language is a bit much, so something like Scratch would be a more appropriate start to their programming journey. After they’ve learned to be comfortable with the basic concepts, they can then transition over to a “real” programming language.

For the second category, I think a good teaching language is absolutely imperative. There aren’t very many of those. I can only think of Basic, Logo, Pascal, Scheme, and Smalltalk. A good teaching language lets you focus on what really matters: learning the basic programming concepts. At this early stage, you shouldn’t have to be dealing with the peculiarities of your starting language. I’m referring to languages like Java, Python, JavaScript, C, C++.

(For learning the basic concepts of object-oriented programming, the most widely used paradigm in the IT industry, there is no better teaching language than Smalltalk.)

However, I should mention that I know of one 10-year-old girl who began her programming journey with Java. Java! Even I find Java a bit intimidating. But there will always be exceptions that prove the rule.

Another comment about my tutorial was that there was too much attention given to things unrelated to programming (that is to say, unrelated to coding algorithms with a programming language). Things like Linux and Raspberry Pi hardware and C language interface. Here, I vehemently disagree.

The activity of programing, that is, of software creation, goes far, far beyond mere “coding” of algorithms. Most programming tutorials focus too much on the programming language and hardly anything on problem-solving. Here is a list of problems, for example, that I encountered in writing my Smalltalk tutorial sample application:

  1. Hardware installation (Raspberry Pi device).
  2. Operating system installation (Raspbian, a Debian derivative specifically for the Raspberry Pi).
  3. Understanding the capabilities of the Pharo environment, including things like Morphic, uFFI, and SUnit.
  4. Analyzing an open source C codebase in order to understand how to use it.
  5. Editing a background image using GIMP.

These are the kinds of problems that any software developer may face. What if your desktop PC breaks down during development? What if Windows becomes horribly corrupted? What if you need to use completely undocumented source code written by an unknown party (this is much more common than you may think)?

When I was writing web applications, a great deal of time and energy went into adapting and modifying software assets like images, videos, audio files, etc. My point is that the list of problems is endless. If all you know is how to code an algorithm, you won’t get very far in programming.

To understand how to program a computer, you must understand the computer.

Don’t treat the hardware as a mystical black box. Dive into its guts. Study its internals. Memory layout. Disk format.

Understand the computer at the operating system level (Linux). Shell scripts. Package management.

Eventually, you will need to know a bit of C language. It’s unavoidable. C language underpins the entire IT industry.

But otherwise you do most of your coding in higher-level languages like Smalltalk, Python, Java, Go, etc. My tutorial gently guides you into the above-mentioned areas. There is further to go, of course, but this is just the first step in your journey.