Make example code interactive

🌱May 9, 2024.
seedling 🌱
2 minutes read ⏱

Seeing a snippet of example code is extremely helpful. It concretely demonstrates how to implement an algorithm, use an API, configure a library, or just about anything else. Code snippets are crucial element of excellent technical writing. Code snippets have one massive gap, though: you can’t execute the code!

While seeing an example of code is very helpful, interacting with the code is even better. When working with a type system, seeing what compiles and what doesn’t and how it impacts runtime values fundamental to understanding it. When working with styling or rendering, seeing exactly what gets rendered and being able to change the code and see how the output changes is critical to learning. Seeing how to use an API is helpful, but it’s no substitute for actually sending a requesting and getting a response.

Developers typically learn best through interaction. Interaction shapes thinking, and the experience of interacting with code improves the developer’s ability to think about the code. When it comes to teaching a technical topic, interactive examples are the holy grail.

Don’t stop at showing example code. Make it interactive.

On my blog I Dynamically generate TypeScript Playground links and Add a demo link to TypeScript code blocks. There is usually a way to make more code examples interactive. Figure out how and get it done!