All API code samples should be written as interactive notebooks!

Consider this hypothetical if you will.

What if instead of our current static API documentation for MapGuide Maestro, we delivered API documentation as a series of .net interactive notebook documents? Code examples that are not only editable, but also interactive!

Behold! A .net interactive notebook explaining how how to use the Maestro API to render an image of a map.

Want to try this code sample yourself? In addition to having MapGuide Open Source installed locally, you will need Visual Studio Code and the .NET Interactive Notebooks extension installed. Once both are installed, you can download this interactive notebook and save it with a .dib extension. Once downloaded, open the .dib file in VSCode and you can run and play around with the code just like the video above.

I believe this is a game-changer for writing API documentation. I have had the same revelation with interactive notebooks for API documentation as I did with the discovery of storybook for designing, developing and showcasing React components. With tools like this, you are actively incentivized to maintain your API docs and its a win-win for your (developer) userbase who get better quality API docs in the process.

The "killer app" for me is if there was a way to either:

• Self-host these interactive notebooks on a asp.net core application
• Export these interactive notebooks to blazor WASM so it can be hosted as static web content on something like GitHub pages

Because right now you need specific tools to consume these interactive notebooks. The tipping point  for me will be if you can consume these interactive notebooks straight from your web browser!