Tutorial Writing: Clarify Your Prerequisites

Writing accessible and learner-friendly tutorials.

A few days ago, Anil Dash asked an interesting question on Twitter (actually, he asked it a year ago, but brought it up again recently by retweeting himself):

Essentially, what are the walls that stand between a beginner and learning how to code?

The answers were varied, but one theme that came up a few times was the fact that many programming learning resources make a lot of assumptions about the reader. As an experienced developer writing a tutorial, it’s hard to remember just how basic we need to be for complete beginners:

This was my experience for the first few years of my own learning-to-code journey. Most tutorials I found started with “open up your text editor” or “run X on the command line.” What the heck did that mean?! The tutorials were written for people who had already been initiated into the world of development. They assumed you had a bit of experience already and knew how to get started, that you knew what a text editor and the command line were.

This is a huge problem. First, there aren’t many resources written with complete beginners in mind. Most resources for learning programming skills are written for people who already have a fundamental level of understanding. As Jeremy Keith says, “There are lots of great articles and tutorials out there for professional web developers—Smashing Magazine, A List Apart, CSS Tricks, etc.—but not so much for complete beginners.” Even if a tutorial is meant to be for beginners, it’s hard to remember all of the details that a beginner might not know yet, so beginners end up getting stuck and feeling frustrated.

Second, if a tutorial is written for intermediate to advanced programmers, that fact isn’t clear to a beginner. A beginner looking at a tutorial has no way of knowing if they’re prepared for the tutorial unless the tutorial tells them the prerequisites. When they attempt it, it feels like stumbling around in the dark trying to find any rock to trip on that might help you figure out the right direction.

Writing tutorials for intermediate or advanced programmers isn’t a bad thing. If you write tutorials, you don’t want to have to write every tutorial as though it’s for a complete beginner. But it’s super helpful when a resource has a paragraph at the beginning outlining the experience level you should have before using said resource, and a couple links to help you get that experience if you don’t have it. And it’s amazing when people spend time writing resources for complete beginners because there is a lack of resources available for that skill level.

As resource writers, we should do two things:

  1. Spend time writing material that is truly geared toward beginners—make zero assumptions about previous skill level and explain everything.
  2. Leave a trail of breadcrumbs at the beginning of our intermediate and advanced resources. At the beginning of the resource, explain to the audience who the tutorial is for and what experience level they should have before attempting to understand your tutorial. If it’s not for beginners, link to a few places a beginner should start instead to gain the fundamentals needed to understand the resource.

It would be great if we had a standardized way to do this across the industry, but here’s an example—please feel free to use it and adjust it for your needs:

Understanding JavaScript Object Constructors

This tutorial is meant for intermediate developers. To learn most effectively from this tutorial and avoid frustration you should understand the following:

To figure out what skills your audience needs for your tutorial, go through your tutorial yourself and pay attention to what skills you’re using to demonstrate your topic, even if they’re not skills you’re explaining in the tutorial itself. Make a list of them, and then find resources for those topics. Since you’ve already learned these things yourself, it’s likely that you already know of some that are good.

The beginning initiation to a subject is an exciting place to work for a teacher because it can mean the difference between someone giving up learning and someone having the fundamental skills to be able to continue learning and growing long after you’re done working with them. Let’s give learners more resources that meet them where they’re at, and help them find the right place for them in the huge array of learning resources available by clarifying who our resource is meant for and guiding them toward resources appropriate for their skill level.

In an effort to provide more beginner resources and put these ideas into action, I’m also publishing an Introduction to Text Editors and the Command Line for beginners alongside this post!

Late Night Code Club Newsletter

It’s midnight. You’re huddled in the restricted section of the library, eyes glued to powerful tomes—Creating Killer Websites! Resilient Web Design! The Pragmatic Programmer! You get a missive from your co-conspirators in the Late Night Code Club—another night of adventurous learning is about to begin.

If you enjoy these posts and want to read more, I’d like to invite you to join the Late Night Code Club by signing up for the newsletter—it’s all about learning and teaching programming. We’re exploring the metaskills that hide between the tutorials, programming as part of a creative practice, and uncovering the secrets that make the web magical. In each newsletter you’ll receive updates about new posts as well as other resources and ideas all about learning programming! It’ll be short, interesting, and encouraging for learners and teachers. See you there!