Technical Tutorials: How to Write Good Technical Tutorials (2023)

Technical Tutorials are everywhere in the technical writing world—possessing vast utilities. Whether you are trying to sell a product to your developer audience, you are trying to onboard your developer audience to get them up and running using your product, or you are trying to help other developers learn to use certain software technologies, tutorials are always a tool you will find handy to fulfill all these functions.

Paying attention to how you create tutorial content is very important. If you don’t know what’s right or wrong about creating tutorials, you might create tutorials that have inconsistent qualities: some well-written, others, badly written. 

We’re certain this content would prove most useful for software engineers that are without much experience writing tutorials. Instead of going the trial and error route, they can get up and running creating great tutorials with all the right ingredients.

That said, there is another point also worth pointing out: when it comes to technical writing, tutorials and how-tos are different. Therefore, You can read more about the difference between technical tutorials and technical how-tos and they differ from each other.

What is a Technical Tutorial?

Technical tutorials are learning-oriented in nature. The goal of a technical tutorial is to help a learner use a tool, a framework, or a product—usually, for the first time. When writing a tutorial, you must see yourself as a teacher helping a student learn to do something they have no knowledge of.

Danielle Procida defined tutorials as lessons that take the reader by the hand through a series of steps to complete a project of some kind in his article “the ideal of a tutorial“. 

In other words, as a technical writer creating a technical tutorial you take the position of a teacher holding the hand of the learner to ensure they are able to use a tool, or product successfully, and most importantly, ensuring the learner is faced with no bumps and frustrations in achieving this goal.

This fact demands extra care from you and that you pay attention to include certain sections to ensure you create well-rounded technical tutorial content. Technical tutorial content fails when a learner is unable to learn to use a tool or product.

That said, let’s talk about rules to abide by in creating good technical tutorials.

Rules for Creating Good Technical Tutorials

Below we are going to explore the top 6 rules for creating good technical tutorials. These rules will help you create even better technical content when integrated into your technical writing process.

Give the Learner a Full Picture of the Goal To Be Achieved

It is of utmost importance to be clear about the end result to be achieved right from the beginning of a tutorial. This allows the learners to form an idea of what is to be achieved right from the start.

You must not underestimate the relaxing sensation this requirement has on the learner. By including this requirement, you empathize with the learner. 

This allows the learner, who has absolutely nothing to expect of the new tool or product, to feel relieved as they are able to set some expectations and hence, feel in control and at ease, within the learning experience you are delivering to them via your tutorial.

 This requirement leans heavily into understanding that the human mind finds peace and control in things being predictable. You create this sense of peace and the feeling of control when you include this requirement.

This implies also that you do not surprise the learner by going outside the goal. Not delivering according to the expectations of the learner is a bad practice.

Leave surprises for suspense novels and movies. It is not a tool you should keep in your toolbox as a technical writer.

Inspire Confidence by Giving a Sense of Progress

Technical tutorials involve a lot of hand-holding exercises from the technical writer. Even after giving the learner a full picture of what the end result is, you can further empathize with the learner by including mini-goals. 

That is, telling the learner the result achieved after each step covered in the tutorial. This gives the learner a sense of achievement that further strengthens their confidence, making them feel more at peace and in control.

This is especially important for lengthy technical tutorials that might involve a lot of steps, and a bunch of things to complete to arrive at the end result. 

You will lose the learner if you go from start to finish in tutorials of this nature and you fail at intervals to inform the learner on their progress and what is left to be achieved. 

Including this requirement is like giving a short break— for resting and delivering mini-lectures—to tourists as a guide taking them on a long journey. A guide would lose the confidence of his tourists—and even inspire fear— if he fails to allow such “short breaks”.

If you want to understand how this requirement is implemented practically, check out the Django official documentation tutorial. The technical tutorial is made up of several parts; each part— their ends—you can consider a short break that helps the learner know his/her progress.

Provide Only Minimum Explanation

There is a reason technical tutorials are called tutorials: they are meant to provide practical knowledge, not theoretical knowledge.

In other words, except absolutely necessary, resist the need to explain concepts. Instead, you will do well by pointing the learner to other articles or documentation that provide explanations of those concepts.

This is also important as it helps the learner stay focused on the goal at hand instead of getting distracted.

A moment of absolute necessity when you need to include some explanation might involve scenarios when understanding a concept would be of necessity to enable the learner to understand the steps you have laid out in your tutorial. 

A technical tutorial is of no use if the learner doesn’t understand the steps you are asking them to do.

Once again, you can peruse the Django official documentation tutorial for practical implementation of this.

Avoid Alternatives

As a software engineer, you probably know that achieving a certain result can be implemented in several ways; some ways, perhaps, more efficiently than others.

In technical tutorials, you must understand that it is best to stick to a single way of achieving the desired result. Including several code implementations to achieve a given result would confuse and upset the learner.

The goal is to help the learner get started using the tool or product as fast as possible, not to display your coding prowess.

Ensure the Tutorial Works on All Supported Platforms

You must ensure to test your tutorial on all platforms—say, OS like Windows, Mac, and Linux—you have mentioned it would work on.

Ensure to also re-run the tests when you make changes to your tutorial. It would save learners a whole lot of stress. 

Summary

A good technical tutorial takes the learner through a join from a newbie to a certain level promised by the tutorial.

For more guidance on the rules of writing good tutorials, check out the Diataxis framework and the Good Docs Project. The Good Docs Project is particularly useful in helping you identify important sections to include in creating a good tutorial.

So that’s it on how to create better tutorials. Comment your thoughts for more clarification and if you found it useful.

Contentre helps technical writers stay organized and gain more clients. Grow your technical writing career in one place.

Now that you’re here, let me briefly recap the most important features Contentre can offer you:

• Organize your content in categories, topics, and tags
• Create and manage multiple clients
• Create and manage multiple personalized portfolios
• Get statistical analytics of your content revenue, top categories, and tags.

Try it now. It’s free