Interactive playgrounds

08 December, 2021

In December 2021, I delivered a talk at React Conf about how we could leverage the tools we have at our disposal, such as React and MDX, to introduce more active learning experiences to our documentation and articles.

This is a follow-up to that talk. Below, you'll find some background thoughts, a curated list of docs and personal blogs that are merging the lines between static and interactive; passive and active. As well as tools and resources to inspire you to build your own.


I've always loved reading, but when I was learning to code, I often struggled reading technical docs and articles. I used to think it was because of my lack of experience (which was partly true of course) but now that I'm a Developer Advocate, I'm starting to understand that effective knowledge sharing isn't just dependant on the consumer, it's also up to the creator and how clearly they're able to transfer information.

Regardless of your level of experience, your ability to understand new topics will depend on external factors such as how well and clear the information is presented.

When we were children, we learned through play and interaction. Learning felt effortless when it was fun. But as we have grown older, our learning methods changed; from active (interacting, playing, building) to passive (reading, watching, listening) learning.

As the web emerged as a medium, we started sharing knowledge through text and images. Technology progressed and we added audio and video to the mix. Each of these types of content certainly have their place, but you may have noticed that they still primarily used for passive learning.

One under-utilised opportunity for active learning the web allows is interaction. Creating interactive content is both more time consuming and more technically challenging. But if active learning is more effective, I think it's worth a shot.

As developers who are already creating rich and interactive components as part of our applications, we're perfectly positioned to create more effective learning experiences through "interactive playgrounds".







Out-of-the-box solutions:

  • Code Hike - easily build code tutorials with MDX and React.
  • Docusaurus - quickly build documentation sites.
  • Nextra - a Next.js static site generator.

Custom solutions:

If you're looking to build your own custom solution, there are a couple of different tools and resources that help with the implementation of MDX.

In addition to the tools above, you may want to consider looking into plugins that allow you to intercept and manipulate the transformation between markdown and your final output (JSX, JS or HTML).

Thank you to everyone who shared their favourite examples with me on Twitter and if you've seen any exceptional examples that are not listed here, PRs are welcome.

Made With Passion By Beriffa Group and CDN by Moralpark®