Creating documentation used to be extremely important in every engineering endeavor, but now, when so many teams work remotely, it's pretty much a critical aspect of our work. As software engineers, we are used to reading docs – and sometimes, reading is enough: you just remember some method's parameters, and that's it – go back to your code and use it.
But quite often it's far more beneficial to see an example code being actually evaluated, see the results… and maybe even edit it a bit to compare the changes. You might have seen some open-source projects (eg. TypeScript or Svelte) already including a kind of embedded playgrounds on their documentation pages. But building your own solution from scratch is a venture which not a lot of teams can afford.
Because of this, many of the world's largest companies & OSS projects have adopted StackBlitz to power their interactive documentation. This year in particular we've seen a substantial increase in usage (over 2 million developers per month!). In this post we want to share how our users are accelerating their docs learning experiences, and how you can too!
We'll get to the nitty-gritty in a moment, but here's a short overview of what we are talking about here:
- @stackblitz/sdk is a 3kb JS library that allows you to programmatically create & embed such environments
- Where it excels is wherever having a live example will enrich your library's documentation
Before diving in, you might wonder if this is something that's even worth the effort, and the easiest way to gauge that is by seeing if other companies and projects are already successfully using this tool. The answer is: totally!
Here are some of the most notable places to get you started:
- TypeScript (Microsoft)
- Angular (Google)
- React (Facebook)
- lit-element and lit-html (Google Chrome)
- RxJS (Netflix)
- Material (Google)
- Project Clarity (VMWare)
- Kendo UI
- Ant Design
... to name a few 🙂
npm install @stackblitz/sdk or just add the script to your page:
and now you can use the global
StackBlitzSDK object to take full control over the StackBlitz VM! Using that you can:
- open a new project in a new tab
- embed a project on the current page
- open or embed GitHub repositories
- and more!
How you proceed depends on your specific circumstances – we've worked hard to make the SDK as flexible as possible, so to learn more take a peek at the SDK documentation.
Pretty much! 😅
But hey, just to show you that it really is that simple, here's a minimal example:
'index.html': `<h1>Hello world!</h1>`,
'index.js': `alert('Woohoo! We can start documenting!')`
description: `My First Docs!`,
💡 We have just bound this code to a click event on the following , so you can actually click it (go ahead!) and see the demo opening in the new tab. Nifty! 😃
It is really an amazing experience for a developer to be able to tinker with code they're reading about, without having to set all kinds of boilerplate up. If you want to make your documentation this much richer my advice is: just try it. Add it in one crucial place – maybe the most used example, or maybe the most complex one. Discuss it with your team, ask your users for their opinion, and I bet you will fall in love with it as much as we & millions of others have!
And if you have any questions, don't hesitate to contact me at tomek in the @stackblitz.com domain or drop into my Twitter DM (@sulco).
Let's work on the docs!