Monthly Archives: January 2020

Examples vs. Tutorials

I’ve been writing software since my first computer in the 1980’s (a commodore 64). Most of that time, I’ve written software for myself, but I did release my first app to the public in the 1990’s. Over all that time, I’ve learned and forgotten quite a bit about computers, computer languages, and how to write code. One thing I’ve never been able to adequately express is how I learn all this stuff. Knowing how you learn something is important because it should inform you how best to tackle something new.

In the realm of showing a learner how to code, there appears to be two major approaches: code examples and tutorials. Examples are short snippets of code that shows you how to do something specific. Tutorials, on the other hand, are similar but go through the process of writing the example within a broader context of a larger application. Typically, you’ll see code examples in places like stack overflow and tutorials in books, book-like websites, and videos. The reality, however, is that code examples work best for understanding languages, since you don’t need a full app to understand how pointers work, and tutorials work best for most complex systems such as frameworks use in applications.

My favorite programming book I’ve used is an old C book. I don’t use it much today, but it got me through writing my first C-based application for designing spherical geodesic grids. From the time picking up that book, a compiler, and getting a working piece of code was about a week or two. Why did that book work for me? It was an example-based book. It didn’t try to lead me through building an app, just explained the concepts and showed examples. For example, if I needed to figure out how to write output to disk, there was a chapter on file IO that would explain it. I stuck with C for a long time because of that book.

I never really “got” other versions of C (at least until Objective-C). There probably is a host of reasons for that, but I tend to blame how I learn. I learn by having a problem I need to solve. Up until 1999-2000, C, bash, and perl could solve all my problems. C plus plus should have been in there somewhere, but it wasn’t because I couldn’t wrap my head around it at the time. In addition to having languages that did the job, the resources I used at the time were more tutorial based.

I quickly discovered that I had a basic axiom:

I don’t want to spend time building someone else’s example apps. I want to write MY apps.

After all, that’s why I’m trying to learn this thing, right? I keep picking up learning resources that are tutorial-based and I fail to get through them and learn what I need because of a basic reality of tutorial apps:

Tutorials will never EVER show you how to write your app.

Tutorials show you how to write the tutorial app. It’s not fair to say that tutorials are not useful – they will help you figure things out, no question. It’s not a bad way to teach you things, particularly if they work for you. If something requires multiple steps are often easier to understand with series of tutorials. But for me, they typically fall down because the tutorials do not match my needs perfectly so they don’t show you critical pieces that fit my problem.

For example, I’m reading a book to help me though understanding a complex API right now (which is why I’m writing this now). It’s tutorial based, which is quite typical in this day and age. However, I could not find anywhere in the book a minimum starting point for using the API. The book started with a tutorial with the tutorial code going a bit too far into a specific problem. This mean that me trying to apply this tutorial caused me a great deal of confusion trying to figure out what I could dump from the tutorial to get to that minimum state. It took downloading tons of example code from Apple to find what I needed. Once I did that, I was ready to move to the next step. Guess what? There were no tutorials in the book that covered that at all…

The above doesn’t mean the book isn’t useful. It still is, but the tutorial code is almost useless to me.

Remember, when I try to learn something new, I have things I am trying to accomplish. I’m not doing it out of pure curiosity. I don’t want to spend a month going through a tutorial book realizing that I didn’t actually learn what I needed to do in the first place. That’s a large amount of time that the project grinds to a halt. Worse, it’s time away from my family that isn’t at least productive. I’m still not entirely sure what it is that I need, but tutorials are not it.