Tutorial Writing: Clarify Your Prerequisites
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):
So, what made you stop trying to learn how to code? I'm curious about the barriers that get erected.— Anil Dash (@anildash) September 29, 2015
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:
@anildash literally stuff like "where do I type code into?" "How do I get python on my computer?" "How do I save a program and make it run"— Alex Hern (@alexhern) September 29, 2015
@anildash 'Beginner' courses that are actually intermediate. Lack of detectable progress. Being overwhelmed with information. Jargon. Time.— Bryan 👾 Clark (@bryanclark) December 6, 2016
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:
- Spend time writing material that is truly geared toward beginners—make zero assumptions about previous skill level and explain everything.
- 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:
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!