by Geoffrey Grosenbach

For many years I’ve felt slightly guilty that, even though I earn a living creating documentation, I rarely start learning by reading about a language or API. Instead, I open up my terminal and get right to hacking on the code before I really know what I’m doing.

Afterward, I’ll read up on the API docs or work through a step-by-step guide.

A few months ago, I passed a year working at HashiCorp. In between learning about cloud infrastructure, services, security, and application delivery, I’ve continued to learn about how to teach technical topics in a way that resonates with people.

This last week, the eye opener was thinking about how developers like to experience a language or API for the first time. We like to do first and then understand later.

Why?

Momentum

It's easier to learn more of a thing if you are already learning something.

Easily reversible

Mistakes in software cost less than mistakes in other industries, so doing it wrong can be part of the learning process.

Action/Result

If we know what will happen, it's easier to assign meaning to the initial action that causes it.

Hands on

Merely reading or watching engages less of the exploratory brain than actively running commands or typing code.

Learning why on the second round

When we run commands as our first experience with a piece of software, we can map that experience back to what we read or watch.

▼▼▼

Momentum

I think about the first few years that I learned to compile or install software with make. I ran make && make install hundreds of times before I learned to read a Makefile or write one myself. Why? Because there’s the thrill of seeing text stream down the screen like something out of the Matrix, then finally result in success or spit out an error. You feel like you’ve accomplished something, or at least made progress toward it. That sense of success keeps you going and makes you want to learn more.

One of my favorite concepts from video game design is “time to first kill”. Although it sounds violent, it’s the idea that, if you have to play a game for 30 minutes before doing anything meaningful, you’ll lose interest. So game designers ensure that your first few seconds involve meeting another character or finding a powerup or completing some satisfying activity. Something to give you the feeling that “I can do this!”

If you start with free momentum in the first 30 seconds, it’s easier to keep going.

Instructional design is no different. Students want to feel that they’ve made progress, even if it’s just a little bit. If we’re delivering content online or students have the option to bail at any time, then early and frequent success is even more important.

This is one of the things I enjoy about HashiCorp software. Every application can be run instantly in development mode without any configuration or other setup. Want to run a private DNS server so your microservices can find each other? No problem! Run Consul in development mode with one command.

$ consul agent -dev

After you’ve verified that your system is capable of running the binary, you can go back and learn about how to write a configuration file, tag your services, connect multiple clusters, etc.

It’s easier to learn more of a thing if you are already learning something.

Easily reversible

I mentioned the concept of Do First, Understand Later to a friend who teaches nursing. She pointed out an important distinction between software and other fields.

In medicine, the consequences would be disastrous if a new nurse tried to insert an IV before understanding where veins are located or how a needle interacts with the skin. So we require that professionals study theory before they go hands-on with a lab exercise on an actual human.

But in software, consequences are easily reversible. So it’s common to take action and then backtrack if it doesn’t turn out as expected.

Even a complex cloud infrastructure setup of compute instances and networking configuration can be created and deleted with a single terraform destroy command, which makes it much easier to try, try again, and then learn about what happened.

Action/Result

Another reason we like to do before understanding is because software development relies on so many supporting parts of the environment. If they don’t work, we will hit a wall and have to pause the learning process to get things in order. Even if I take the correct action, it may not produce the correct result.

This is why I often start by wondering, “Will this even work on my machine (or at all)?” If I can first start the webserver or compile the app or provision my basic infrastructure, I can be confident that when I run into a conceptual roadblock, I won’t have to doubt my setup.

So I like to start by running code so I can have confidence that an action will produce the expected result, or at least that the result is possible if I do the rest of the steps correctly.

If we know what will happen, it’s easier to assign meaning to the initial action that causes it.

Hands on

Learning by doing wakes up my mind in a different way than reading or watching. In fact, sometimes I choose to watch a video on a subject because I know it will require less concentration and less mental energy than other ways of learning.

But when I have the energy and am ready to devote my full mental capacity to learning, I start by doing. I can ask questions and pursue my curiosity. I can try a command or delete a line of code to see if it works or breaks in the way I expect it to. By learning interactively, I can learn in an order that makes sense to me.

And then when I’m ready, I can read through a prepared sequence of documents that someone else has assembled. They work together: in documentation I can learn more about the concepts than I can easily discover on my own.

Merely reading or watching engages less of the exploratory brain than actively running commands or typing code.

Learning why on the second round

Last, I like to learn by doing first because it means that when I’m finally ready to read any kind of documentation, I’m learning for the second time. I remember what I saw before, and it corresponds to what I’m reading now. And I know that my environment is set up so I can try any part of the tutorial at any time.

When we run commands as our first experience with a piece of software, we can map that experience back to what we read or watch.

Conclusion

I no longer feel guilty about skipping the documentation until later. In fact, I think that admitting this common approach to learning helps me create better tutorials. I can make sure that any tutorial is accompanied by downloadable code that can be run with a single command and minimal dependencies. Or maybe I’ll setup a pre-baked in-browser interactive environment to follow along with.

It also makes learning more collaborative. Grab a friend and learn together, even if neither of you have done any of the prerequisities.

▲▲▲