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, design systems teams many of the world’s largest companies in addition to the maintainers of many popular 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!
Breaking down into nuts and bolts
We’ll get to the nitty-gritty in a moment, but here’s a short overview of what we are talking about here:
- StackBlitz is an extremely fast and lightweight online IDE with a built-in compiler/dev-server for JavaScript & TypeScript projects
- @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
Who’s using it?
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)
- ng-bootstrap
- Kendo UI
- Ant Design
… to name a few 🙂
So how do I start?
Either npm install @stackblitz/sdk or just add the script to your page:
<script
src="https://unpkg.com/@stackblitz/sdk/bundles/sdk.umd.js">
</script>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.
Wait… is that it?
Pretty much! 😅
But hey, just to show you that it really is that simple, here’s a minimal example:
StackBlitzSDK.openProject({
files: {
'index.html': `<h1>Hello world!</h1>`,
'index.js': `alert('Woohoo! We can start documenting!')`
},
template: 'javascript',
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!
