A technical tutorial is a detailed instructional guide that teaches individuals how to perform a specific task or learn a particular skill in a specialized field. These tutorials provide step-by-step instructions, explanations, and examples to help users understand and implement the concepts being taught.
Creating technical tutorials is a regular part of your job if you are an educator, content creator, subject matter expert, or a DevRel person like me. Maintaining a consistent structure across tutorials offers several benefits to creators as well as readers.
In this post, I will dissect the structure of a typical tutorial that society would potentially reward as "good." I will lay out the key sections of a tutorial, their goals, and what information should go into them. Whether you are a beginner or an experienced creator, use this post as a guiding light to structure your next tutorial.
What makes a good tutorial?
A good tutorial often goes beyond a typical instruction list and touches upon several factors.
In my opinion, a tutorial qualifies as "good" if it meets the following criteria.
Clarity of Explanation: Clear explanations are crucial for user comprehension. A good tutorial should present concepts in a straightforward and understandable manner, avoiding unnecessary complexity. Users should be able to follow the content without confusion.
Structural Organization: A logical and well-organized structure is vital for user navigation and comprehension. Headings, subheadings, and a clear flow of information contribute to a seamless learning experience. Users should be able to follow the progression of the tutorial easily.
Completeness: The tutorial should cover all necessary aspects of the topic without leaving critical information gaps. It should strike a balance between providing enough depth to facilitate understanding and avoiding unnecessary details that might overwhelm users.
Engagement: Engaging content keeps users interested and motivated. A good tutorial employs a variety of content types, such as text, images, videos, and interactive elements. The writing style should be engaging, making the learning experience enjoyable.
Usability: Usability refers to how easy it is for users to navigate and follow the tutorial. Clear instructions, a user-friendly layout, and well-defined steps contribute to usability. Users should be able to access and implement the information without encountering unnecessary obstacles.
Beginner creators might take a while to master all these criteria at once. But they can certainly start at some point and work iteratively to make tutorials better over time.
I can help you by providing a starting point - a template that helps you structure your tutorials better. This template divides a tutorial into several sections and guides you to put the right information in the right places.
The key sections of a tutorial include:
- Introduction - Essential summary of the tutorial
- Overview - The problem you are trying to solve with the tutorial
- Prerequisites - What the reader must have before getting started.
- Execution - Step-by-step instructions
- Validation - How should the reader verify the tutorial outcome?
- Tearing down - Cleaning up resources
- Conclusion - Takeaways
Let me dive deep into each section next.
The seven sections of a good tutorial
Introduction
This section introduces the tutorial and briefly explains what to expect in the content. After reading the introduction, the reader can decide whether to continue or quit reading, saving him a few minutes in his life.
The hook and the summary are two elements you can include in the introduction to persuade the reader to continue reading the rest of the content.
The hook: A few powerful sentences explaining why the reader should read the tutorial. In most cases, this can be the problem you are trying to solve, summarized in 2–3 sentences. The closer the hook gets to the reader's problem, the more readers continue reading.
Summary of the article (TLDR): What can the reader expect in the tutorial? What's the outcome, and what are the takeaways?
Make sure to keep the introduction short and sweet to lure in more readers to the content. Ideally, you should limit it to 3–4 short paragraphs.
The Overview
This is where you should describe two things in particular.
Problem statement: What problem are you trying to solve with the tutorial? What benefits does it provide? Spend a paragraph or two mentioning these points.
Solution architecture: How are you trying to solve the problems? What's the high-level solution architecture would look like? Mention the technology components you will use in the tutorial and highlight the data flow, connectivity, and user interactions among them.
I often find it easy to pick a fictitious use case and build your narrative around that. For example, to build a data pipeline from a database to a data lake, you can think of an online store use case.
Include visuals as much as possible in this section to provide more clarity to the reader. I highly recommend including a high-level solutions architecture diagram capturing the tutorial scenario. That way, the reader can quickly capture what you are trying to do, even if you miss some instructions.
Prerequisites
You should mention what tools, technologies, and components the reader must have beforehand to complete the tutorial.
For example, the reader must have installed something like a Git CLI, a database, or a build tool in the local workstation or should create a SaaS account before proceeding with the tutorial. Use a bulleted list to mention them.
Furthermore, if certain tools are specific to a platform, highlight them as well. For example, some Linux build tools don't work in Windows, causing the reader to install an alternative, like WSL, before starting the tutorial.
Finished code repo: Not all readers are made equal. Some readers are impatient; they want to see how the completed solution would look like, so they copy code from it :) You can help these readers by pushing the completed solution code into a public Git repo and sharing its link here.
Execution
Now that we have set the stage so far, we've come to the meat of the tutorial. This is where you provide step-by-step, Detailed guidance on each stage of the process or task.
Be sure to provide clear instructions in the order of their dependency. Add screenshots and diagrams as needed - the more, the merrier.
After each instruction, provide the reader the means to verify whether they have executed that properly. For example, if the instruction is about creating a table, the reader can verify the operation by running an SQL SELECT statement against the table.
Validation
Once the reader finishes following instructions, you should provide a way of verifying the end-to-end solution.
Method of integration testing: Provide a sample data set to verify the connectivity, data flow, and expected output of the solution the reader has built. You can include a screenshot or a visual portraying the final solution if the instructions were followed correctly.
Known issues and challenges: Sometimes, certain steps can't be completed due to technical challenges or limitations. Therefore, state any known issues and inform the reader about possible workarounds.
Tearing down
This is an optional step where you instruct the reader to destroy the environment and clean things up to save costs. For example, you can ask the user to turn off an EC2 instance after following the tutorial to reduce the cloud bill.
Conclusion
At last, we come to the end of the tutorial. This is where we wrap things up.
Collecting the thoughts: Reiterate what you have accomplished in the tutorial. Spend the first paragraph of the conclusion wrapping things up.
Taking it to the next level: The tutorial might have shown a thin slice of a solution that addresses a simple problem. Suggest to the reader how to extend the solution to implement a real-world solution and take it to production. You don't have to be detailed here, but highlight a few potential steps necessary as a guideline.
Call to action: Dedicate the last paragraph to insert your CTA, driving satisfied readers to your marketing funnel. After putting so much time and effort into creating the tutorial, you may lure the reader into the next step of your lead funnel ;)
Summary
Technical tutorials can be packaged and presented in various formats, including written articles, video tutorials, interactive online courses, or a combination of these mediums. You can use this post as a template to structure your tutorials, regardless of the format they are presented.
As a rule of thumb, try to cut your content at the 2000 word mark because most readers, including me, have a short attention span, and it isn't easy to navigate and follow a long document. Use a tutorial series if the content goes beyond 2000 words.
I hope you learned something new today. If you are interested in reading posts about DevRel, writing, and productivity, subscribe to my newsletter The Tributary
Top comments (0)