Turn confusing code into a personal tutorial with AI
Create Personal Code Tutorials with AI
Ever stare at a piece of code and feel a gap between “it works” and “I truly get it”?
This is a pattern to use AI to help. It’s a useful as a starting point to learn new APIs, or doing any kind of review of code.
There was a chat component using HTMX for server communication and Alpine.js for client-side reactivity. The code worked, but the interplay between the two felt like magic. And I don’t like magic I don’t understand in code.
So I used AI to turn the source code into a documented tutorial. The result was very helpful for my own learning.
The Problem: “Magic” Integration
I had a ChatInput component. It needed to handle file uploads, preview them, let you remove them, and reset everything after a message was sent via HTMX.
This required integration between HTMX and Alpine.js to have a good UX.
HTMX submits the form. Easy enough.
Alpine.js has to manage a temporary list of files, show/hide the preview area, and handle click events to remove files.
I have a somewhat vague understanding of how it worked, and I hadn’t used much Alpine JS before.
The Prompt: From Code to Classroom
I handed AI the entire Python component file and asked this:
Take this Python code. It uses HTMX and Alpine.js. Add comments to make it a detailed tutorial explaining the Alpine.js concepts and patterns being used. Explain why each directive (
x-data,@click,x-for, etc.) is used in this specific context.
It asks the AI to become a teacher and embed the lesson directly into the code I was already looking at. Here’s a snippet from the output.
The AI refactored my comments into a structured tutorial.
The next step and tutorial hell
Tutorials are great for learning, and AI being able to create customized tutorials is incredibly powerful. But tutorials are harmful if only passively consumed, leading to something commonly called tutorial hell! Here’s what to do after reading an AI created (or any tutorials).
Read the tutorial to understand the concepts
Build a minimal new minimal showing just 1 concept you didn’t know previously. Repeat this step for every concept you didn’t previously know.
Rebuild what the tutorial taught without looking at the tutorial contents
Incorporate into a new project. There’s probably things you’ve done that you could refactor to be better with what you now know!
The goal is to keep yourself actively learning. Passive consumption (lectures, tutorials, reading books, etc.) is only the first step!