Write Better Programming Tutorials

Share your knowledge more effectively, with more people

We publish a lot of tutorials at Better Programming. If you’ve mastered something in programming — a process, a task, a method — you can probably write a tutorial about it that other people will find useful. It could get lots of views!

Say you’re working with a newly released version of a highly popular tool or framework and you learn how to do something tricky that’s not yet well documented — you have valuable knowledge to share.

Even if you’re just starting out on your programming journey, you could create something useful for other learners. In fact, basic subjects have a larger potential audience — there are always more beginners than advanced practitioners in any field.

But … to be successful you do need to know how to write an effective tutorial.

Remember:

It’s a learning resource

The style, structure, and scope of the piece should be designed to fit a learning objective. Ideally, the learning objective is clearly stated, right in the title.

In this piece, I’m going to list the ingredients that go into a well-designed programming tutorial.

A Strong Introduction

You should always have an introduction.

Some writers, usually with very short pieces, jump straight into the walk-through, but I think this is usually a mistake. Yes, if you’ve picked a good topic lots of your readers will know from the headline that they want to read it, but there are lots of other readers out there — people curious enough to click but who still need convincing. A short introduction before the instructions gives more people an opportunity to discover that they want to read the rest of the piece.

The introduction should cover:

• What the reader will learn from the tutorial (the learning objective)
• Whether it’s part of a larger process (is this one of a series of pieces?)
• Knowledge prerequisites (what the learner needs to know to understand this process)
• Physical prerequisites (what the learner needs to have installed on their computer)

Write Clearly and Simply

It’s always important to write clearly — but it’s absolutely crucial that a walk-through is written as clearly and simply as possible.

In the introduction, you can make jokes and express a bit of your personality, but when you get to the process you should adopt a totally straightforward, transparent writing style. Transparent means the reader doesn’t even notice it. They don’t think “what great writing” or “how beautifully put” because they’re too busy taking in the information without noticing how it has been presented.

You should also stick rigorously to the steps you’re covering — this is not the place for asides or tangents. Think of it as a lesson. A good teacher might take a relaxed, informal approach in a class, but when the time comes to get down to it they’ll focus on the work and make sure the students are doing the same.

This is one of those situations where you don’t necessarily want to write the same way that you talk. “Now go ahead and open up your terminal” might sound winningly informal in person, but in a written tutorial, that type of casual language just slows the transmission of information and increases the chance of confusion. Just write “Open the terminal.” This isn’t bossy or overly formal in the right context: It’s simply neutral.

To write clearly:

• Don’t use long complicated sentences — if in doubt, split it into two
• Don’t combine steps into long paragraphs — give each step its own space
• Don’t use unnecessarily long words
• Avoid grammatical redundancies (always)

Use the Right Voice

One issue I’ve come across a few times is when a tutorial opens with something like this: “Let’s say you are working on a project in React …” Because they’ve presented a hypothetical situation (“Let’s say …”), the writer then starts using the conditional tense, “You would then have to create …” “Next, you would build it and run it.” Ten or 20 steps later, and they’re still using “You would” for every instruction. This is unnecessary, and it makes things difficult to read — it introduces friction. Use the conditional tense sparingly.

Instead, use the imperative form. This is what you use when you’re telling someone to do something, like “Now open your terminal.” Don’t worry if you don’t expect anyone to actually be following along. Writing instructions like this is the most common way to do it — therefore its expected by readers and is thus the most transparent.

Break It Up

Walk-throughs can get repetitive. Systems walk-throughs can involve scrolling through endless “click here” instructions, so it’s important to keep the reader engaged and oriented. If you have more than 15 or so separate steps, it’s a good idea to break it up somehow.

Look for natural pauses — where you’ve finished a stage of the process, for example — to take a break from the main flow of the process. Use this moment’s pause to review what’s been achieved and what steps are left.

Use Screengrabs … But Not Too Many

For systems walk-throughs, screengrabs can be a real aid to understanding. However, they take up a lot of screen space, and if each screen is only minimally different from the last, they can make a short process walk-through difficult to navigate. It’s too easy to lose your place when you’re scrolling through numerous, similar-looking screengrabs.

Save screengrabs for new screens and to highlight any easy-to-miss visual elements in the process.

Code

The most important thing to stress about code in your Better Programming tutorials is this: You should include it. It’s better to show what you’re talking about than to just link to a GitHub repository for the piece (although, please, do that as well).

As I discussed in my previous piece, “Writing Tips for Programmers,” Gists in Medium are currently, unfortunately, not to be trusted. So that means putting all code between ticks like this. Two of these ticks ` formats everything between them, or three of them, like this ```, in front of a paragraph, formats the whole thing.

If you need to include very long chunks of code in the middle of a tutorial, be sure to consider how long it’ll take for the reader to digest them and how they will look on the page. A big formatted piece of code will disrupt the flow of a walk-through, so it’s a good time to take a break to reorient the reader, as discussed above.

A Final Word

In many ways, tutorials are easy to write. You’ve already done all the hard work by learning the process in the first place. If you’re an inexperienced writer, they’re a good way to get started writing because they have a clearly defined scope. Just outline exactly what task or process you’re covering and then carefully go through it, step by step. You don’t really need to argue or make a case for anything (although, as I said, making a case that the task is widely useful can increase your readership.)

So, what are you waiting for? Write a tutorial today!