This guide covers our guidelines to structure tutorials well and make them as enjoyable as possible for users.
In this guide, you’ll learn:
We’ll first look at the structure of a good tutorial and then discuss writing tutorials for different users.
This guide doesn’t cover grammar and formatting. You can find those in our writing guidelines.
The header is an introduction that sells the reader on the tutorial or lesson.
In a condensed form, it gives them everything they need to understand what the tutorial is about. They should be able to identify at a glance if this is the material they’re looking for.
The reader needs to know what they’re getting in return for reading to the end. For that, you need to help the reader visualize the result and stay motivated.
To do so:
In a series, you should do the above both in the project’s introduction and in every lesson:
You should split the rest of your tutorial into logical sections following the outline you gave in the introduction. <!— This still needs a reference to the guide covering the outline —>
Avoid headings that sound like labels (eg: “PathFinder class”). Instead, phrase each section’s heading to explain the problem you’re going to solve in the section (eg: “Coding a class to find the optimal path between two point”).
Inside each section, detail the steps to achieve the result.
When the tutorial requires editing existing code, favor appending code at the end of existing functions; Avoid adding code at the start or in the middle of a function. It makes it harder for the user to track changes.
If there is no elegant way around adding or substituting code in the middle of a function, find a way to highlight the change to make it easily identifiable for the user. <!— Do we want to set a method here? for example: git’s +/- in front of added/removed lines? —>
Code listings should include comments that explain:
Why you decided to write a given function or part of the function this way.
What the code does without paraphrasing it.
You can alternatively write those explanations before a short code listing.
A good tutorial should use the flow that feels most natural to the reader.
It’s a balancing act that involves:
Avoiding frequent back-and-forth between files.
Avoiding a robotic structure. In other words:
The robotic structure is most convenient for the writer, but feels like copying mindlessly for the reader, even if you do your best to explain everything.
The most natural flow for readers is adding game mechanics and features one after the other.
You want to limit frequent context switches yet teach mechanics one at a time. Your role as a tutor is to arrange the order in which you cover everything to minimize friction.
Ideally, at the end of each section, the reader should be able to run their game or edited scene without errors even if not much is happening at this point.
Similarly, at the end of every lesson in a series, the game should be in a testable and working state.
At the end of a tutorial, give the reader a summary of what they achieved and learned. Give them insights into how they can go further, and if possible, give them a related lesson they can check out next.