Coding tutorials typically consist of explanations and code. In a video tutorial, we can let the user see the code and listen to our explanations at the same time. This is a very natural way of learning and it is always clear what part of the code is currently being explained.
However, video tutorials come with several downsides: they are hard to navigate, consume a lot of bandwidth and are also hard to change/update for the author. Moreover it is not possible to copy the code out of a video.
Text Based Tutorials
In a text based tutorial we need to put a lot of thought into arranging explanations and parts of the code. There should not be too much code before it is being explained. And also, there should not be too much explanation before seeing the code. Therefore the author of the tutorial has to split up and arrange explanations and code in a smart way. This can be very tricky. If you split your code into tiny slices, the reader may not be able to grasp the context anymore.
A New Approach
I came up with a new approach that aims to combine the advantages of both worlds. I coded up a prototype that I call Codepled. It consists of a code area, a text area and a table of contents that can be hidden to save space. While you read through the text, the code panel updates according to the part of the text that is currently in the viewport. Parts of the code window can be highlighted, such that it is always clear to which part of the code the currently visible text is referring to.
The combined advantages are:
- Clear and simple dependency between code and text
- Authors can change code and text easily
- Easy navigation
- Copy code and text
- Low bandwidth consumption
I converted some of my coding tutorials into Codepleds to provide some examples:
If you are interested in the project, want to contribute or simply share your feedback, make sure to visit the project page: https://github.com/Annoraaq/codepled
Happy coding! 🐱💻