How I Used the Diataxis Framework to Create My First YouTube Tutorial

Many of us have tried doing something completely new. And while we draw inspiration from the work of those who excel in that area, we often struggle with where to begin and how to add our own unique touch to it. That’s exactly how I felt when I decided to create my first YouTube tutorial.

For months, the idea of making programming videos for YouTube lingered in my mind. It seemed like the perfect way to share knowledge, connect with a wider audience, and try something new. But every time I sat down to plan my video, I felt stuck. I kept asking myself: How should the content flow? How should it progress? I also didn’t want to simply copy what others I admired had done. I wanted my video to stand out without overcomplicating things.

Then, a thought occurred to me—why not lean into something I already knew? As a technical writer, I’ve written several tutorials and guides using the Diataxis framework. If it could help me write clear and progressive documentation, why not apply it to video creation? So if you don’t know what Diataxis is, it’s a framework that prescribes a systematic approach to technical documentation authoring. Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. Diátaxis solves problems related to documentation content (what to write), style (how to write it) and architecture (how to organise it). Excerpt from https://diataxis.fr

The moment I adopted the Diataxis tutorial approach as the guide for my video tutorial, everything began to make sense. I didn’t just jump into coding, I started with a clear goal by showing viewers the finished project. I believe this approach helps viewers understand what they’re working toward and keeps them engaged.

I also embraced mistakes as part of the learning process. For instance, I deliberately avoided using React useState hook at the beginning of the video, knowing it would cause the app to fail to update. When the app didn’t work as expected, I used it as an opportunity to teach. I explained the problem and demonstrated why useState is important. Throughout the video, I ensured every step led to a visible, meaningful result. Each small success reassured viewers they’re on the right track. I highlighted what they should observe at each stage—from running the code to display the elements in the components to inspecting variables in the console. This helps in making connections between causes and effects, a key principle of the Diataxis tutorial approach.

Also, I minimized explanations. Instead of diving into a lengthy theoretical discussion about useState, I simply mentioned that I’d use it to trigger a rerender. This keeps the focus on doing rather than getting bogged down in abstract concepts. At every stage, I tied actions back to the viewers’ sense of progress and their end goal. By the end of the video, they hadn’t just learned about useState, they had used it, seen it in action, and understood its importance.

In conclusion, creating my first programming video taught me that the skills we develop in one area of our career can help us in another area. For me, using the Diataxis tutorial approach wasn’t about achieving perfection—it was about giving myself a starting point and the confidence to try. So if you’re hesitating to try something new because you aren’t sure of where to start, you can lean into your current skills and experience. The result may not be perfect, but it’s a start. And sometimes, that’s all you need to take the next step.

Please subscribe to my YouTube channel.