5 Things I Always Do Before Writing a Technical Tutorial

Technical tutorials are detailed guides that teach individuals how to perform identified task and or learn skills pertaining to a specific field.

Technical tutorials are not just a collection of different steps, It is an invitation , a guided transformation of some sort. A good tutorial will not just be a list of commands showing what buttons to press. A good tutorial should help readers think clearly, avoid common errors, and confidently apply new knowledge.

As a technical writer, here are 5 things I always do before writing a technical tutorial.

1. Define the reader

Before typing a word, these are some questions I like to ask myself

• Who am I writing the tutorial for ?

• What level of experience will they have ?

• What will they need ?

• Are they just getting started with this tool or are they trying to switch from something else?

Writing a technical tutorial without knowing your reader is like trying to build a house without a blueprint - you might end up with walls, but no doors, and a roof where the foundation should be.

2. Clarifying the Outcome

The second thing I do before writing a technical tutorial is answering the question: “What will I be able to do after this?“

This is something I feel every good tutorial should answer. If I cannot define the outcome in one sentence, then I am not ready to begin writing the tutorial.

✅ ”By the end of this tutorial, you will have successfully integrated Cerbos with Kubernetes”

❌ ”This tutorial will teach you something about Cerbos and Kubernetes”

3. Research

The third thing I do before writing is research

Why do I research? Because the tutorial I'm trying to write probably exist and may probably have flaws.

I look at:

• What people complain about.

• What GitHub issues get posted.

• Which steps confuse people the most.

After looking at all that, I ask my self: How can I write the same thing, better, faster, or clearer?🤔

4. Test run the Tool Myself

Testing the process I'm writing about is a non-negotiable step for me when I'm writing a technical tutorial.

If I'm writing about using Docker compose or deploying on vercel, I like to do it from scratch:

• To note errors I may come across,

• to capture potential pain points,

• record outputs, screenshots to use for my tutorials, and solutions.

Its good practice to ensure that process you will be writing on works.

5. Create an Outline

Creating an outline before writing is a very crucial step because a streamlined outline will help keep the tutorial clear, well structured and focused, which will lead to a more logical output.

Below is my go to skeleton:

1. Introduction - Explain the tutorials goal and what the user will learn.

2. Overview - State clearly the problem you're addressing, the background information concerning the problem, and state clearly what the user will be able to do after completing the tutorial.

3. Prerequisites - List all the necessary tools, software, or knowledge required to follow the tutorial. State any assumptions that will made about the users level of knowledge.

4. Step-by-Step Instructions (Execution)- This will include; Logical Flow, Examples, Code Snippets, Visuals, Transitions.

5. Validation - Explain how the user will ensure they have the completed the tutorial successfully and also describe the output of the tutorial.

6. Conclusion - A summary of the main points of the tutorial. Suggestions of additional steps the user can take for continued learning.

6. Conclusion

In conclusion, writing a technical tutorial involves more than just listing steps; it’s about guiding readers through a learning journey. By defining your reader, clarifying the outcome, researching what already exists, testing every step yourself, and creating a detailed outline, you set a solid foundation for tutorials that are clear, and helpful.

Great tutorials don’t just teach — they empower readers to apply new skills confidently. When you approach tutorials as transformation guides rather than simple instructions, you create content that developers (and your clients) will value and trust.

If you're a writer, web developer, or engineer:

What are the steps you take before writing tutorials?

Comment down below 👇🏿👇🏿👇🏿