Author Archives: loufranco

Playable, not Gamified

In Playing a Book, I said:

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.

I want to clarify that I don’t mean “Gamification”. I don’t want a book to seem like a game—I want it to literally be a game.

In a gamified book, you would just write the book as normal and then give the user a badge when they complete a chapter. Or maybe you’d assign points to various things.

The distinction I am trying to draw is that playability is something you start with to drive your design. Gamification is something you slap on at the end.

Icon-first Development

I’m currently working on an app to help me with intermittent fasting. I developed it icon-first.

My apps mostly exist to drive my own learning. Right now, I am trying to learn SwiftUI and visual design.

To do the latter, I’ve been reading Designing Visual Interfaces, which came highly recommended from Amy Hoy. The first chapter teaches techniques for simplification, and so I decided to not think about the UI at all at first, but to find some kind of unifying metaphor by trying to design an icon that meant “intermittent fasting” to me.

In intermittent fasting, you try to eat in a defined time window each day, commonly eight hours (so, fasting sixteen hours). Many people just pick a time window and use it every day (e.g. 10-6), but that doesn’t work for me—I want to decide each day what woks best for my schedule.

So, with that vague idea, I started sketching

To get loose, I just drew a circle. Then, a pie chart that showed the feeding window as a third of the whole. Then, I tried a ring. Eventually, I just had a vertical stripe, then a horizontal one. I realized the essence was “thirds”—8 is a one-third of 24. I also had the idea that I could hide an “F” in the design (for Fast-o-Mat, the name of the app). I don’t like icons that have a word or letter in them, but a hidden letter in the design is fine with me.

At this point, I thought I could go into Pixelmator and refine. There have been many iterations. This one imagines showing seven days of history in a vertical stack.

I really like how the “F” is hidden in this one. The problem was that when I went to make this UI, I didn’t like using it. Seven days is way too cumbersome when you mostly just want to deal with today (and maybe yesterday and tomorrow).

Also, a phone is tall and narrow, so this design overemphasizes the week over the day when you render it in portrait. It’s hard to edit the today-bar, because it’s too narrow.

So, I worked on my UI and eventually settled on only showing three days (yesterday, today, and tomorrow). I went back to the icon and made this:

This does not have as recognizable an “F” in it, but that’s not the priority, so I am ok with that. Each vertical bar is a day and its position shows the part of the day you are feeding. The Today bar is bigger than the other days, because that’s the most important. On a phone, this whole things is stretched vertically, so there’s plenty of tap space on the parts of the bar you might need to interact with.

I am still working on refining the UI. I’ll follow-up when that is closer with thoughts on how that evolved.

Working through the icon helped me focus on simplicity. Designing Visual Interfaces talks about designs being instantly recognizable and impossible to use incorrectly. A lot of this comes from reducing the number of elements.

The second chapter is about visual perception, using things like contrast and size to allow the user to group elements into layers and order them.

Using the constraint of designing an icon first helped me focus on those aspects of design.

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.

New Article in the Swift Companion: Methods

Yesterday, I wrote that books should get you to write code, not just read it. I’ve been working on a companion to Apple’s Swift Programming Language book that helps you do that by offering exercises for each chapter.

I just published the companion to the Methods chapter on App-o-Mat. If you want to start from the beginning, go to the outline of Section 1. If you understand the content of the corresponding chapter, the exercises are meant to be very easy. If you are having trouble with them, it would be a good idea to review the chapter again before moving on.

Learn Programming by Writing Programs

Most programming books and tutorials show you code and explain it. What they should be doing is describing code they want you to write.

Here are some examples:

  • Project Euler presents one numerical programming problem at a time. You must provide the correct answer (a number) before you can see the next one.
  • Apple’s Swift playground books on iPad also make you write code. Your programs move a robot around a board, and it knows if you achieved the goal they specified.
  • The Unwrap app by Paul Hudson. It combines video and written lessons with challenges of various types including writing Swift code. Each lesson is very small.
  • freeCodeCamp breaks down learning web development into tiny coding challenges that are auto-checked by the site.
  • Cryptopals teaches you how to write cryptography and code that attacks it with lessons you check against the expected output.

The big advantage of this style is each level can be very focussed on using just one new skill. In this talk by Kathy Sierra (and in her book Badass) she covers the research behind skill acquisition. One big idea is that you need to break skills down into tiny sub-skills. The reason is so you can master part of a skill, rather than half-master a full skill, which is hard to improve later.

She also says that learners need feedback, which these systems do by verifying your work automatically (or by having an expected output you can check).

In contrast, most programming tutorials are quite long and don’t make you create your own programs (so can’t really provide feedback).

If all you do is read or type in the code in the tutorial, you aren’t practicing a core skill of programming, which is to write code on your own to match a specification.

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 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 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 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.

Tech Jobs Are Not Performances, So Why Do We Audition?

I went to see an orchestra perform Beethoven’s Fifth last night, and it reminded me about what bothers me about typical tech interviews. If you want to be in an orchestra, you need to audition. That makes sense because an audition is close to what the job actually is—a performance. This also makes sense for actors, comedians, dancers, etc.

Programming is not a performance

A typical tech job is not a performance. For one, there is no audience. And, unlike a performance, we make tons of small mistakes and corrections along the way. Imagine a band performing a song like we usually program—it’d be a mess and not very entertaining (or very entertaining if you think of it as avant-garde).

I’ve known this for a while. In fact, when I get asked for interview advice, I usually say this directly: “Treat it like you are a violinist trying out for the orchestra. Practice, practice, practice. Ask your recruiter what kind of code you’d typically have to write during the interview (algorithmic, UI, a full-stack app), and practice that. Practice the tools/IDE, frameworks, language, etc. Think of it more like performing a piece.”

Now, to be clear, I’m not a big fan of this kind of interview. But, often as job-seekers, we don’t have the ability to change this—especially if there’s a specific job we want. I had a 22+ year career, wrote a book about iOS development, and had many public artifacts of my work, but I got my last job by passing several “auditions” that I practiced for. I personally don’t intend to ever do that again, but I wanted this specific job, and this was the only way to get it.

Instead, let’s try portfolio review

What I think would be better is a portfolio review. This is what you’d do if you hired an artist, craftsperson, or other professional where the job is to produce works. Portfolios give us insight into what the person could make given typical conditions and not under time constraints with every mistyped keystroke interpreted as a short-coming.

We already know this. When hiring consultants to do tech work, it’s the norm to look at portfolios, and not to do a tech screen. When I was consulting, I prepared a website with a description of my credentials and links to my work. I was never asked to live-code to get a consulting gig.

The problem is that not everyone has a job that produces public works. Even if the product is public, we need to see the code, since that’s the part a programmer makes. There is some privilege in being able to have time to create these works.

But, I don’t think it needs to be a huge piece—it’s likely that an interviewer could only spend 20-30 minutes looking at it. The important thing is that the work conveys a positive answer to the question: “can this person do the job?”.

I wrote about portfolio-based interviews back in 2011.

If you don’t have a public project, and are thinking of preparing a portfolio piece, it doesn’t have to be a giant project. I think something with a dozen or so code files is about the right size to review. If you are showing me something much larger, then point out a part that I should focus on.

I’m kind of surprised that this hasn’t become more common by now, as it did seem like it was happening organically. GitHub links have been common for a while. StackOverflow introduced Developer Stories in 2016, which are focussed on showcasing your work. I have never seen one as part of an application.

Bonus: They could be blind

When orchestras started using blind auditions, gender balance improved:

Using a screen to conceal candidates from the jury during preliminary auditions increased the likelihood that a female musician would advance to the next round by 11 percentage points. During the final round, “blind” auditions increased the likelihood of female musicians being selected by 30%.

We could probably do our current tech interviews blind using a voice changer over a screen sharing service, but it would be awkward. A portfolio review is easy to do blind.

In fact, tech conferences that use anonymized proposals, often result in a more balanced speaker group. See !!Con:

Proposals will be anonymized to avoid bias. Although we ask for your name, email address, and so on in the proposal submission form, only one or two organizers who serve as anonymizers will actually see this information, and they won’t review your proposal. The rest of the organizing team will review your proposal without knowing who you are.

Here are the speakers that resulted from that process.

A blind process won’t guarantee a balanced result, but I believe we have enough evidence to believe it would improve balance.

What Employers Could Do

If an employer wanted to move to a portfolio review, I’d suggest something like the following

  1. Explain it clearly in the job posting
  2. Make it clear that the piece does not have to be big
  3. Ask for code and writing samples (blogs, StackOverflow answers, etc)
  4. Give some idea of the judging criteria
  5. Offer to pay applicants to create the portfolio piece if they don’t have one. I would say to do this on self-reported need. Perhaps after passing a resume screen
  6. Do it blind
  7. Create a rubric that takes many attributes into account (not just “algorithm implementation”). Examples: documentation, tests, consistent code style, reasonable abstractions, correct use of language/framework idioms.
  8. Train the judges and have each portfolio scored by many people

And for their current employees—give them time to create public works (open-source, blogs, etc).

I’d love to hear any any experiences on both sides of a code portfolio review. What worked, what didn’t. If you have something like a code portfolio prepared, I’d love to see a link.