How to Write a Good Programming Tutorial

I’ve been following a lot of tutorials recently. Some were excellent, some so-so, and some so bad I couldn’t finish them. I’m not an expert, but I can tell you what I do and don’t like about all the ones I’ve looked at so far. Some of it might be subjective, but I think most is not.

1. State the Goal

Don’t just launch right into your tutorial without telling your readers what they will achieve when they’re done. If you are going to teach them to make something, show them the end product and give a brief overview of how it works.

If you’re just teaching some programming fundamentals and don’t have any main project, tell your students what they will know how to do by the time they’re finished. Maybe they’ll have a good understanding of how to implement loops in their code or they’ll know how to use classes.

2. Know Your Audience

Who is your tutorial for? Is it aimed at true beginners who’ve never programmed in their lives? Intermediate learners trying to get some projects under their belt? Work out who you’re writing for, make it clear at the start of your tutorial, and cater to them accordingly. I often find that people label their tutorials as being for beginners but fail to explain the basic elements of programming. You need to start from the beginning.

Tell them how to set up a programming environment and what their choices are concerning text editors and/or IDEs. Explain what variables and conditionals are early. If you don’t want to write all that then link to another resource that covers it. Don’t just leave it out.

You can always include a link to a section that can be skipped to if you want to accommodate both beginner and more experienced students.

3. Spelling, Punctuation and Grammar

Yeah, yeah. It’s a programming tutorial, not an English lesson, right? I can definitely forgive a typo here and there. They are hard to avoid, even if you do proofread your work. No one’s perfect, after all.

But some tutorials are full of spelling mistakes and have sentences that don’t really make sense. I think this often happens when the author is not a native English speaker. If this is you, please find someone to edit your work before your put it out there. You definitely have an excuse for not having perfect English, but it’s a big turn-off to readers when your content is so hard to read. I’ll say now that I’d be willing to proofread posts for anyone free of charge, as long as it’s content that you are posting for free.

4. Use Examples

If you are guiding people through building a specific project then you should include your code to show them what they should be typing. Showing is better than telling. I’m always frustrated when I’m following a tutorial and part of the code is missing. Most people nowadays put their example code on Github so it’s less of a problem, and I’m glad to see that.

If your tutorial is more general, then still use code examples. Maybe you’re telling someone how to build their first web page. Even if you’re intending for them to customize it to their liking, it’s still a good idea for you create an example for them to follow along with if they so choose.

If you’re teaching a programming concept such as conditionals, use a code snippet showing their use. Just explaining how they work isn’t enough.

5. Break It Up

I don’t really like giant walls of text. And I don’t just mean, ‘please use paragraphs’, though that is important too. Tell the user what the next step is and make sure it’s small enough to explain in a few lines. Show the required code whether it’s in a video, a screenshot or just typed between paragraphs. Ideally, you shouldn’t introduce a lot of new code at a time as it can be overwhelming. I personally find it’s more likely I’ll make a mistake when typing it out. (I don’t copy and paste; I find it isn’t good for learning.)

After that, tell the user what they should expect after completing that section, and show the working version of the project or exercise if applicable. Then move on to the next part.

These sections could be more general if your tutorial is aimed at more advanced learners. For example, an intermediate learner probably knows how to run their code in the command line without you telling them how, but a beginner course should explain this explicitly, at least the first few times.

6. Don’t Be Afraid of Errors

I actually like it when a tutorial has you do something which results in an error. It’s a good learning opportunity, because a big part of learning to program is learning to debug your code. I’m not necessarily saying you should be creating errors everywhere on purpose, but think of common mistakes that a student might make. Think of the mistakes you made when you were starting out.

Explain how to read the error, what it means and how to fix it. If you are writing for beginners, this may be a good time to mention how to effectively Google problems that you can’t work out how to fix yourself.

7. Explain Jargon

If you are writing a tutorial about a topic that your intended audience knows little about, it’s fair to assume that they won’t know about common terms or acronyms. Don’t just start writing about global variables or AWS without explaining what they mean or stand for first.

8. Include Date and Version Numbers

I often find it hard to find up to date tutorials because it isn’t always easy to find when they were published or what version of Python or Django they’re using. Please make sure your post is dated (easy enough to do if your tutorial is in a blog) and include the version number of everything you are using. The IT world is constantly changing, and what worked a year ago may not work today. If you aren’t explicit about the fact that you are using Django 1.9 and someone with 2.2 installed tries to follow your tutorial, they might just think it sucks, when the real problem is that the thing you’re telling them to do does not work in their version.

It’s probably also a good idea to update your tutorials as technology changes, but I realize this is often easier said than done. At the very least, be clear about your versions numbers.

9. Provide Practice Opportunities

I think it’s important to try and get people to work things out for themselves where possible. Whenever you’re about to implement another part of a project, or going to write a new script, think about whether you might have covered enough by this stage for your students to work out what to do on their own.

Tell them what the next step is and perhaps give hints that you think will help. Then explain how to do it as usual, since some people won’t get it, and others may benefit from seeing how you solve the problem since it could be different from their solution.

10. Don’t Leave People Hanging

This one is connected to the previous – don’t tell your readers to ‘do this next part on your own’ and then just assume they succeeded and move on. I hate getting stuck and being unable to continue because I was too dumb to work out how to do a certain step.

If you want to include a challenge section, that is a little different, and opinions here will probably differ, but I think it’s a good idea to at least include the answer in a Github repository. One of the things I hate the most is when I fail to do something and can’t for the life of me figure how to do it even when I search Google. Please just give us the answers!

Conclusion

I really do appreciate all the people who take the time to create awesome tutorials for people like me who are trying to learn. I plan on making some myself one day, when I feel I’m knowledgeable enough. I will of course have to be careful not to break any of my own rules!