Improving tutorials with "The Code Sandwich"

When you're writing a tutorial that involves a lot of code, you can help your readers understand the code better by using an approach I call the "code sandwich", which looks like this:

• A brief high-level description of the code.
• The code itself.
• A deeper dive into the tricky bits of the code.

This approach lets the reader know what they're doing and why they're doing it, and keeps them motivated and engaged.

When I'm editing content, I often come across sentences like this:

Create a new file in your editor called index.html and paste in this code:

This sentence is then followed by a large chunk of code without much context at all. The reader can certainly copy and paste the code, but the author hasn't given the learner a chance to understand what they've done. Some learners will stop here and dig in to the code, trying to figure it out themselves, while others will give up entirely.

Replacing this with the "code sandwich" approach provides two benefits:

1. It provides the context the learner needs
2. It slows the author down and gets them to think about what they're actually trying to teach.

That second bit is important; in order to teach something, you have to be able to understand it well enough to explain it. Going through the act of explaining it will then improve your own understanding of the topic. Everyone wins.

Here's an example of the "code sandwich" in action. Let's start with something you might typically see which does not follow this approach:

Create the Dockerfile in your editor and paste in the following content:

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html

This example provides the code, but it lacks the explanation a learner might need. Here are questions some learners might have:

• What's nginx:alpine and why are we choosing this over nginx:latest or another image?
• Why are we copying index.html into the /usr/share/nginx/html folder?

When you're writing technical content, you're not there to answer the learner's questions, but you can use your experience to anticipate them.

So here's how I'd recommend rewriting it using the "code sandwich" to provide the motivation, context, and detail:

Create a new text file called Dockerfile in your editor. Add the following code which defines a new Docker image that bundles your index.html page with the Nginx web server:

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html

This Dockerfile uses the nginx:alpine image, based on the popular Alpine Linux project. Using this image as a base results in a smaller image. By default, Nginx serves files from the /usr/share/nginx/html directory. By copying the index.html file into that directory, you don't have to modify Nginx's configuration files to point to your content.

This "code sandwich" version provides the details a reader may need to understand both what and why you're having them add the code to the project.

The next time you're writing a tutorial and you're asking someone to add some code to their project, consider using this approach. Examine the code, consider why you're having the reader add it, and explain what it does before you ask them to add it. Then dive deeper into the nuances. If you follow this pattern, your readers will have fewer questions, and you'll help them be more successful. After all, that's why you're sharing your words and code in the first place!