Category Archives: Books

Programming Tutorials Should be Vaguer

The basic template for programming tutorials is:

  1. An introduction with a motivating example
  2. Step-by-step how-to style instructions with code
  3. Conclusion

But, if the way to learn programming is to write programs, this template breaks down at step 2. At the end of the tutorial, you have working code, but since your brain was engaged in reading and typing (or copying), it’s hard to absorb the information. I know that when I have “done” tutorials, I didn’t really learn the material in a way where I could do it on my own later.

So, perhaps tutorials shouldn’t give you all of the code, but instead provide enough information for you to write it yourself.

For example, here’s a code sample from a tutorial I wrote about GameplayKit:

enum GameOutcome: String {
    case win
    case reset
}

Instead of showing this, I could have written: “Declare a string-based enum named GameOutcome with two cases: win and reset.” There could have been a button that revealed the code.

Another way would be to use Steve McConnell’s coding technique from Code Complete. He suggests writing the comments first and then writing the code beneath (and between the comment lines), so like this:

// GameOutcome is an enum of the possible final states: win and reset.
// It needs to be a String-based enum because we use the
// raw value in GameplayKit methods that take an AnyObject.

This really only works for very simple code (I know because I tried to write the above example for more complex samples and couldn’t). A tutorial like this would get the reader playing instead of reading and help them practice composing code instead of copying it.

Review of Quantum Country

Yesterday, I wrote about how Quantum Country is helping me understand what books are for. As a recap, QC is a series of essays about quantum computing. You should think of it like a text book—they are not trying to write a pop-sci, hand-wavy, high-level overview, but a serious science/math book suitable for a college level class. Basic linear algebra is a pre-requisite to understanding it.

The book is also an exercise in a new form they call the “mnemonic medium”. Embedded throughout the text are interactive flash cards that test you on the material you just read. Depending on how you rate your own memory, they will used spaced-repetition algorithms to show you cards more or less often—the aim is to show you a card just before you will forget the answer. Using this system, you should be able to remember the content indefinitely (and need to visit and test yourself less often over time).

Does this work? I was tempted to review the book by just listing out the facts I remember, but honestly I think that would be boring to read. I did do that exercise, and I can remember quite a bit right now, but I just finished the book last week. I read it fairly slowly over six weeks and did the cards as prompted. I also did a few of the proposed exercises (which involve linear algebra), but not all of them.

In addition to the mechanics of quantum computing, I do think I also understand the higher level “point” of it. I don’t think I could make my own circuit to do something, but I could do the math to analyze a circuit. I have also gone on youtube and watched the more challenging presentations on quantum computing (the similarly math-y ones) and was able to follow them quite easily. If the “What is it for?” for Quantum Country is to teach the reader quantum computing, I can say that it was successful at that for me.

Here is a motivating example of why you’d want to know about quantum computing. In quantum computing, the fundamental unit of computation is a qubit (or quantum bit). They are quite a bit harder to make than our classical bits, but a system of N of them can represent 2^N states, and a state change on that system (affecting every qubit) can be done in constant time.

We are currently extremely limited in the number of qubits we can make and keep stable. Reading the result of the system is noisy and imperfect. However, we have still been able to do computations that are impossible on classical computers (just because of sheer size). This feat is called quantum supremacy, and has been achieved by a few research groups.

The essays include a description of a quantum computing search algorithm that can (probabilistically) find a value in an unordered list in O(π/4*(sqrt(n))) time (instead of O(n)). Just knowing that that is possible and the basics of how it is done was worth the read to me (even though I can’t say I fully understand it).

So, if you can multiply matrices, I would say to read Quantum Country enough to see if it interests you. I would at least try to get through some of the embedded flash cards to experience the mnemonic medium.

What are books for?

Questions are places in your mind where answers fit. If you haven’t asked the question, the answer has nowhere to go.

– Clayton Christensen

Clayton Christensen said that he came up with the disruptive innovation theory by asking the question “why do well-run companies go out of business” when he entered business school. He attributed having a unifying question to guiding his research and being open to answers.

I am similarly thinking about the question “what are books for?” I don’t have a lot of good answers yet, but I have seen something that I think is part of my answer.

I just finished “reading” Quantum Country, which is a series of essays about quantum computing. The material is very challenging, but they have a novel technique for helping you process and remember the content. They embedded flash cards in the text, and the site uses spaced repetition algorithms like I described yesterday in my post about Anki.

So, their answer to what books are for is something like “to transfer knowledge from the writer to the reader”, which is an obvious answer, but I have rarely read a book that tries to do this so thoroughly.

There is another answer in this text, somewhat meta, which is “to advance the idea of mnemonic media”, which is what they call this style of book. It’s not surprising that a new form of media would need to explain itself—it’s like how music in new genres needs to explain the genre they are in (see “Rock and Roll is Here to Stay” and “Rapper’s Delight”)

In the world of publishing, there are other possible answers such as “to increase the reputation of the author”, “to entertain while reading”, “to sell related services”.

It’s not so much that I want to know what books are for generally, but more about what I think they should be for. And once I know what they are for, to question whether books are even the right way to deliver on that.

Playing Non-programming Books

Yesterday, I wrote about how to play a programming book by adding bosses to chapters so that you can’t move on until you beat the chapter.

I think it’s clear how you can do this with programming books. I published “bosses” for (as of now) the first ten chapters of The Swift Programming Language. I have more coming.

But, this basic concept can be applied to other books as well, and I am using two tools, Anki and Obsidian to do this for myself. Anki is where I put the facts of the books, Obsidian is where I manage my own thinking.

Anki

Anki is a flash card system that uses spaced-repetition algorithms to aid memorization. You make flash cards while you read to help remember the facts you want to keep top of mind, and then you just “study” them once a day. All the cards you ever make are in one pile, mixed together.

You tell Anki how confidently you remembered the answer, and it will show it to you less often the more confident you are. Over time, when you have made hundreds or thousands of cards, you will still only study 10-15 per day, but Anki will have chosen the ones you were most likely to forget.

Obsidian

Obsidian is just a personal system to manage your own writing. There are many apps in this category, but I use Obsidian because it creates simple markdown files in a folder on my computer, and has all of the features I need (tags, links, search). I like that it is an app on my laptop, not a website.

I am following the note taking system outlined in How to Take Smart Notes, by Sönke Ahrens. I recommend this book for the full details. The high-level summary is that you write notes while you read to develop your own thinking.

Your notes are not quotes from the book. A simple note might be your original restatement of the ideas of the book. My favorite kind of note is applying the ideas of the book to a problem I am working on. If you want to remember a quote from the book, put it in Anki or in a research note in Obsidian (a folder you create just to hold the source material notes). Most of your note taking should be original writing.

Once you have written a note, you link it to related notes, and over time you develop an interconnected web of short bits of writing. Each note is short and represents a single idea—it should be developed as finished, polished paragraphs.

When you want to publish something—a blog post, an article, a podcast script—you can draw on your notes with pre-made bits of writing that you can simply assemble, and then write the connective bits to develop it as an argument.

Playing the book

I have only been following this system for a few weeks, and I have written over 14k words in 81 individual notes. This post draws from some of my notes.

To get back to how to play books, I make writing notes and cards a gate to moving on in a book. If I literally have no original thoughts or nothing in the book is worth remembering, I give serious thought to whether I should continue reading it.

Playing a Book

I’ve been thinking a lot about what books are for. Specifically, non-fiction books, and more specifically programming books. I’ve finally figured out how to describe what I’ve been thinking: You don’t read a programming book, you play one.

I mean play, like playing a game. In a game, you progress through levels by learning and applying skills. At the end of the level, you play against a boss that you have to beat to progress.

In books, you progress through chapters. But, there is nothing that stops you from just reading and reading and reading and well, not learning or applying anything. At the end of a chapter, you can just turn the page and keep going.

Over on App-o-Mat, an iOS content site I maintain, I’ve been working off and on a companion to the The Swift Programming Language book by Apple. I started the companion on Dev.to with a short section on how to read the book, where I said you should it read it side-by-side with an Xcode Playground page open. That you should not copy any code into it, but type code as you learn it. Get used to typing code.

Then, for each chapter, I offer some simple exercises that let you know that you understood the chapter.

I now realize that I was turning chapters into levels with bosses, which make The Swift Programming Language a book you can play.