Back when I started writing for this site, I wrote an article called “Don’t Write Tutorials” in which I discussed the dangers inherent in the glut of hastily-written, poorly-explained “tutorials” that can be found all over the internet. I also wrote a companion article, “Don’t Read Source Code,” wherein I tried to explain the difficulties that can stem from using code (and only code) as a learning resource.

Unfortunately I lost both of those articles in a server move, because I was careless in my backup process. Thanks to archive.org, I can pull up the originals, but rather than simply repost them verbatim I thought I would take the opportunity to re-edit and unify my thoughts on the matter.

What I really wanted to say in those original articles is that understanding code written by others is hard. It’s a skill. It takes practice to master. With experience the task can become easier, but it never really becomes easy.

Code is an artifact of an individual’s thought process. It’s an encoding of the many tiny decisions made by that programmer over several iterations of problem solving. Most importantly, it’s a lossy, error-prone encoding. It can be very hard to tell why a particular decision was made regarding a particular implementation by just examining the source code. I’ve heard code likened to ancient cave paintings, for example — you can generally interpret the what, but the why, the fundamental reasons that motivated the decision to craft those paintings remains a mystery we can only theorize about.

Code is superficial. It lacks the richness, depth and context of the problem it purports to solve, and consequently I think it’s one of the worst ways to study more theoretical or abstract concepts. It is true that good commenting — comments that describe the why — can improve the information density in a code fragment. But we all know that most code we write isn’t ideally commented.

So how does this relate to tutorials? A tutorial is conceptually an oversimplified, direct demonstration of a very specific technique. Online, they most often take the form of little more than verbose-but-redundantly-commented streams of code. There’s very little useful background in most such tutorials, which are typically written by somebody who has only just barely grasped the subject matter at hand. A tutorial written by a capable and experienced author is a separate kind of entity altogether, but like well-commented code, is far more rare a thing.