Writing effective coding tutorials
18 Jul 2022Writing about what you learn, when done well, is a great way to solidify your own knowledge of a topic, stretch yourself professionally, and establish credibility in your field.
In 2020, I started writing tutorial-style articles for Ruby on Rails developers. Writing these articles began as a fun distraction from a stressful job, and as a way to reconnect with web development as a discipline as my day job pulled me further away from regularly writing code. From that beginning as a distracting hobby, I grew to have a passion for writing tutorials as a way to share my knowledge with internet strangers.
Over the last 18 months, my writing has helped me grow my professional network, find new consulting clients, earn a few thousand dollars in (self-published) book sales, and to feel much more confident in my technical skills.
As I’ve worked to improve my own writing, I have read many, many articles from other developers. Many of those articles have been valuable but I also see very common, correctable mistakes from folks who have knowledge to share but struggle with sharing that knowledge effectively.
Today, I’m sharing some of the most common mistakes I see tutorial writers make and how to correct those mistakes to write more effective tutorials. I will also share the simple formula I use when writing new tutorials. Before we begin, there are a few things to keep in mind.
I am writing this from the perspective of someone who writes web development tutorial articles. Most of my articles are “How to build X with Y”, almost always with a concrete, usable component of a web application built by the end of the tutorial. If you are already writing successful tutorials and feel confident in your own formula, you may not learn anything groundbreaking by reading this piece.
The ideas I present in this article should be generally applicable to technical tutorials, but some pieces of advice may not apply directly, depending on what you are writing.
This article does not discuss the distribution of articles or how to build an audience for your hot new tech blog. Today we are focused on improving the quality of your tutorial content. If you write higher quality content, you may be more likely to get some SEO wins or pick up traction in your Twitter niche, but quality is only a piece of the puzzle and, in my experience, only a small piece most of the time. You will not learn how to strike it rich by writing coding tutorials by reading this article, but hopefully you will learn a few things that help you improve your writing.
Also note that I am writing about mistakes I see when reading coding tutorials, especially those published on large platforms like dev.to and Medium where many aspiring writers get started. I am drawing from experience to write this article but I will not link to specific articles as examples of these common mistakes. I am not trying to put anyone contributing free writing to the programming community on blast, so you will have to take my word for it when I call something a “common mistake”.
Let’s dive in.
Write for a specific audience
When you publish a tutorial on the internet, you have no control over who will read your article. Anyone interested in the topic can click on the article and start reading. This means that you are likely to find readers of all experience levels and abilities, and, try as you might, you cannot write an article that effectively caters to all levels of experience.
Despite this, I often see coding tutorials that attempt to write for a huge range of experience levels. This happens most often when the article is demonstrating a very complex interaction requiring strong knowledge in the library or language being used while also spelling out for the reader how to do basic tasks like assigning a variable or opening their terminal.
Instead of trying to write for all possible levels, decide who you are writing for, tailor the content of the article to that level, and then explicitly state who will get the most out of the article in the introduction. If you are writing about an advanced technique that requires a solid grasp of the tech stack you are writing about, tell the reader that and then skip over detailed instructions and explanations for pieces of the project that your advanced readers should understand. If you are writing for more junior folks, slow down and explain things in more detail, narrow the scope if needed, and keep the code simpler to avoid overwhelming the reader with concepts they may be unfamiliar with.
Make a decision about who you are writing for, state that decision clearly, and then write each section of the tutorial with that audience in mind.
Make a promise and keep it
Early in your article, tell the reader what the tutorial will teach them, and then follow through on that commitment.
After reading the first few paragraphs of the article, your reader should know what you are going to help them build and what tools you will use to build it.
Your promise should be clear and specific, like this: “In this article, we are going to use Ruby on Rails and Stimulus to build a drag-and-drop interface for reordering items in a list and saving the users changes to the database. We will use Tailwind to make the list look fancy and the drag-and-drop UX will be powered by Dragula.”
In two sentences, the reader knows exactly what to expect from the rest of the article and they can decide if it is something they are interested in reading.
Once you have made that commitment to the reader, the rest of the article should follow through on that commitment. If you committed to building a drag-and-drop interface with Rails and Stimulus, that’s what every piece of the article should be about.
Most commonly, writers miss the mark on this by never making a promise to the reader. They just dive right into the code without making it clear what is being built. In the worst cases, the tutorial does not have an introduction at all, we just dive right into the code with no context.
Perhaps controversially, I do not think you should rely on the article’s title as the only place you make the article’s goal clear to the reader, especially for more complex tutorials. For the drag-and-drop example, the article title might be “Building a drag-and-drop UI with Rails and Stimulus”. This is a good start, but expanding on that promise early in the body allows us to be more clear about the precise set of tools and techniques used to accomplish the goal. You may find that you can make the promise in the title in some cases, but I find restating the promise in more detail to be more effective at setting the stage for the reader.
Focus on what you’re teaching
After you make a promise to the reader about what you are teaching them, avoid distracting the reader with unexpected or unnecessary code. They signed up to learn X, not Z and W.
This means stripping the tutorial down to its bare essentials so that you can start meeting your promise to readers as efficiently as possible. Distractions often creep in to coding tutorials in these forms:
- Long and complex setups before you can begin working on whatever you have promised to teach the reader.
- Adding complexity to the project that does not help the reader learn about what you promised to teach them. This often happens when the writer wants to show off, not teach. Unless the purpose of the article is to teach the reader that fancy new technique you just learned, keep it simple.
A useful technique to eliminate complicated or long setup steps is to provide a starter repo for readers to clone so they can bypass setup steps that are not part of what you are teaching and dive right into learning. You can see this approach in action in one of my recent articles which required a non-trivial amount of setup to make good use of the library the article was focused on.
A more general technique to keep your readers focused is to read through your first draft and look out for code that could be simplified or that is unrelated to what you are building. Simplify what you can, remove code that is not necessary, and trim explanatory content that is not essential to understanding how the code works.
Create visual checkpoints
Web development tutorials are almost always focused on building a thing that appears on the screen, but writers commonly forget to show the reader what they’ve built.
Visuals (images, gifs, and videos) serve two purposes in tutorial articles.
First, they show the reader what they will build. “A drag-and-drop UI” probably means the same thing to most readers, but adding a gif that shows the drag-and-drop UI in action removes any ambiguity. I like to add an image or gif of the finished product to the introduction of every tutorial I write to make sure the reader knows exactly what we are building.
Second, visuals are a great way to create checkpoints for the reader as they progress through the article. Working all the way through an article only to reach the end and realize that your code isn’t working is a bummer — help your readers avoid this by pausing after each section to check in on what the code they have written should be doing, and, whenever possible, give them a screenshot or a gif to show it in action.
In our drag-and-drop example, our checkpoints might break down to:
- Display a static, unstyled list of items on a page
- Visual support: A screenshot of the list of items in a browser
- Add drag-and-drop functionality to the unstyled front end
- Visual support: A gif of the items being reordered via drag-and-drop
- Persist new order of elements to the database
- Visual support: A gif of items being reordered via drag-and-drop and then refreshing the page to demonstrate the new order persisting
- Styling the list
- Visual support: A gif of drag-and-drop list with updated style and animations in use
Taking the time to create these checkpoints in the tutorial and add a visual for each one is extra work. The payoff is that readers are less likely to get lost as they read your work.
If you are building something without a visual component, it is still helpful to include checkpoints in your tutorial and to try to get creative with ways to include visuals — screenshots of logs, terminal output, or an API response can all be useful ways to give the user a clear way to confirm they are on the right track as they work.
Build incrementally
Closely related to the concept of checkpoints in the last section is building incrementally. Too often, coding tutorials jump right to the finished product. For very simple articles, there may only be one step, but for almost everything worth writing an article about, there are enough steps to break the article down into pieces that can be built sequentially.
If you are reading this article, you have almost certainly encountered a “tutorial” that fails to build incrementally. The author promises to show you how to build a drag-and-drop UI, and then the content of the article is just blocks of code with no context or explanation of how the author arrived there. In the worst cases, you do not even get comments embedded in the code blocks, just a bunch of code that does… something. As a reader, you’re left to figure out the steps on your own and to piece together what all the context-free code does. Reading those tutorials is the owl meme, but for code.
Breaking your articles and explaining each piece as you go has two major benefits.
First, it forces you to think more deeply about the necessary components of what you are building (helping you focus your writing) and makes it much easier for readers to follow your thought process.
Second, breaking your work into coherent, incremental steps helps readers actually learn from your article, rather than just copy and pasting your finished code into their project without understanding what the code does. If you take the time to break your work up you can present the reader with the process you took to arrive at the finished product and you can spend time looking at the interesting decisions you made to build the solution.
Explain the code at the right level
The folks who jump right to the end without showing any of the incremental steps tend to miss the mark on this too. A coding tutorial should teach the reader how to reproduce what you have built. To do this, your article should explain what the code you have written does at an appropriate level of detail for your target audience.
If you are writing for beginners, go into greater detail about concepts and go a bit slower when code gets complex. It is better to explain more than you think you need to than it is to gloss over things that you think might be obvious. Avoid using jargon or terms beginners might not understand, and be generous about linking out to further reading on key concepts they will need to understand.
If a concept is likely to be too confusing for a beginner to grasp, consider whether you need to discuss that topic at all. Perhaps a better approach is to rewrite the code to use a less advanced technique that still solves the problem.
If you are writing for a more advanced audience, do not waste time and energy explaining in detail things they should already know. If you aren’t sure if they know it, mention it briefly and link out to documentation that goes deeper into a concept for those that need a refresher.
If the concept is not core to what you are teaching, feel free to gloss over it and trust that your more advanced audience will be comfortable digging into unknowns.
Check your work
This should be obvious, but all too often I work through an article and realize that the author has skipped a step, made a typo, or otherwise presented code that does not actually work.
Before you publish, read through your article, copy and paste each line, and confirm that it all works as you expect it to. You can’t control readers skipping details, failing to have the right tools installed, or otherwise getting stuck on things because they were in a rush. You can be sure that, when you publish an article, it works like it is supposed to.
You made the reader a promise, keeping it requires checking your work!
A simple formula to get started
Every coding tutorial I write follows the same basic formula. The choice to follow this formula allows me to spend more time thinking about the content of each article and less time worrying about how to present the article to readers.
This formula is intended as an example of what works for me, your mileage may vary. You can see this formula in use in articles like this, this, and this.
Introduction
Tell the reader what you are building in the article, what tools you will use to accomplish the task, and who you are writing for. Include a gif or screenshot of the finished product, when relevant. It usually helps to add a little bit about why the reader might want to read about this topic or why you have chosen to write the article.
In this section you may also find it useful to note the version of tools you are using (“I’m writing this article using Ruby on Rails 7 and Stimulus 3”) so that readers from the distant future know what to expect. I also like to include a link to a Github repo with the final code available so readers can compare their work to yours if they get stuck.
Setup the application
Any setup steps that need to be done to get the reader ready to start building go here. Include a link to a Github repo if setup is complex so readers can skip this step.
Build the application
Break each milestone into a separate section, explain each code block as you go, work in small units, and include visuals frequently to keep the reader on track.
Conclusion
Recap what the reader learned by following along with your tutorial. Add links to further reading and more resources when appropriate. Thank the reader for reading.
Closing thoughts
Writing tutorial articles has been a huge boon to my career. I have grown my skills as a developer and as a writer, built a website that > 0 people visit every day, found new consulting clients, and been able to give back to a community that has given a huge amount to me over the last decade.
My hope in writing this article is that at least one reader will learn something that makes them more successful as a writer. If that’s you, send me a note and say hello.
As always, thanks for reading!