Show HN: Add live runnable code to your dev docs(usedevbook.com)
usedevbook.com
Show HN: Add live runnable code to your dev docs
https://www.usedevbook.com/
33 comments
Very good idea, and you're not alone. The upcoming documentation[0] for React will have a similar feature built on Sandpack[1][2].
[0]: https://beta.reactjs.org/learn
[1]: https://sandpack.codesandbox.io/
[2]: https://news.ycombinator.com/item?id=29417937
[0]: https://beta.reactjs.org/learn
[1]: https://sandpack.codesandbox.io/
[2]: https://news.ycombinator.com/item?id=29417937
We've used https://docusaurus.io/docs/markdown-features/code-blocks#int... do do this ourselves. No need to use codesandbox.
Docusaurus maintainer here
Yes we like MDX and live code blocks to embed natively runnable code in your page.
I don't like the idea of loading a remote iframe much (at least for most cases using JS).
The StackBlitz / WebContainer approach also seems better than a remote VM + iframe
We'll likely use a project called React-Runner in the future, quite similar to our current setup (real native embed) but lighter.
Yes we like MDX and live code blocks to embed natively runnable code in your page.
I don't like the idea of loading a remote iframe much (at least for most cases using JS).
The StackBlitz / WebContainer approach also seems better than a remote VM + iframe
We'll likely use a project called React-Runner in the future, quite similar to our current setup (real native embed) but lighter.
Thank you. I'm a fan of Sandpack and CodeSandbox:)
The dev docs future looks exciting!
The dev docs future looks exciting!
Neat. I guess a useful side effect of running this is that it will be super obvious when the docs contain broken code! How are errors handled? Am I able to see errors that my customers raised while interacting with the docs?
Thanks!
> I guess a useful side effect of running this is that it will be super obvious when the docs contain broken code!
Yes! One of the things we've learned is that companies are building very complicated in-house systems to make sure their docs code snippets are runnable. With Devbook, you could just start a Devbook VM from you CI/CD pipeline and run all the code snippets in the same environment your users will get when they visit your docs.
> How are errors handled? Am I able to see errors that my customers raised while interacting with the docs?
That's what we are exploring right now. We are building a dashboard that would give you an overview of what is happening with your docs code snippets and give you better understanding if developers are struggling with your docs and API/SDK.
> I guess a useful side effect of running this is that it will be super obvious when the docs contain broken code!
Yes! One of the things we've learned is that companies are building very complicated in-house systems to make sure their docs code snippets are runnable. With Devbook, you could just start a Devbook VM from you CI/CD pipeline and run all the code snippets in the same environment your users will get when they visit your docs.
> How are errors handled? Am I able to see errors that my customers raised while interacting with the docs?
That's what we are exploring right now. We are building a dashboard that would give you an overview of what is happening with your docs code snippets and give you better understanding if developers are struggling with your docs and API/SDK.
Since you're using Firecracker, it's hard to understand how it takes 20 seconds to boot a VM.
AWS Lambda worst performer (JVM) I think takes much less than that, like 5 seconds in cold start. You must be loading something really bulky at startup...
Why don't you offer warmed VMs? Like reserved concurrency in AWS Lambda. Preemptively increase the number of VMs (like an auto-scaler) as traffic increases.
AWS Lambda worst performer (JVM) I think takes much less than that, like 5 seconds in cold start. You must be loading something really bulky at startup...
Why don't you offer warmed VMs? Like reserved concurrency in AWS Lambda. Preemptively increase the number of VMs (like an auto-scaler) as traffic increases.
I understand from where your confusion comes from.
We have a few unoptimized things happening on our infra in the moment. We are working on it to make it better and it will be better soon. Most likely around 1-2 seconds.
Once we had the early version ready, we started focusing on figuring out the business side of Devbook and iterating on the product. So certain things aren't as high priority right now but will be very high in the near future.
We have a few unoptimized things happening on our infra in the moment. We are working on it to make it better and it will be better soon. Most likely around 1-2 seconds.
Once we had the early version ready, we started focusing on figuring out the business side of Devbook and iterating on the product. So certain things aren't as high priority right now but will be very high in the near future.
Very cool. maybe a way to go to market would be to sell it as a chrome extension to large corporates or even dev agencies by proving it will make their developers more productive?
i.e. spin up VMs for me when I go to any site, not just the sites which have chosen to use devbook.
I reckon that could make adoption a lot faster/easier and also it means the people/orgs directly receiving the value are the ones paying.
i.e. spin up VMs for me when I go to any site, not just the sites which have chosen to use devbook.
I reckon that could make adoption a lot faster/easier and also it means the people/orgs directly receiving the value are the ones paying.
That's an interesting idea. Flip the adoption.
One tricky thing is to make sure that the code snippet can actually run. Often you need a bit of a bigger context to run the code. Like env vars or dependencies.
One tricky thing is to make sure that the code snippet can actually run. Often you need a bit of a bigger context to run the code. Like env vars or dependencies.
This seems like a great alternative to passing around postman collections separate from documentation
What do you think is the biggest problem with passing Postman collections?
What do you think this "Devbook docs collection" should look like? Just sharing docs with live code snippets?
What do you think this "Devbook docs collection" should look like? Just sharing docs with live code snippets?
Isn't this something similar to Jupiter Books, where you can have executable code?
Devbook allows you to integrate the "interactive code experience" natively into your docs. It's not just embedding an iframe. We can also handle use-cases like CLIs better since you can add a full emulated terminal [0] (like RunOps did on their landing page [1]) to your website and control it with JavaScript.
[0] https://github.com/devbookhq/ui
[1] https://runops.io/
[0] https://github.com/devbookhq/ui
[1] https://runops.io/
But at 18-20 seconds for a VM that is non-starter. Can't you just run it in a container or WASM in the browser? I personally would rather have it external so that it runs in a container in my actual terminal.
That will get better. We are 18-20 seconds without of much optimization as of right now. We have internal demos being able to start under 1 second.
> Can't you just run it in a container or WASM in the browser?
Great thing about VMs is the security, quick snapshotting, and resource oversubscription.
> WASM in the browser
I personally love WASM and am very excited about it. There are however a lot of use-cases where WASM doesn't cut it. Having full environments with a file system and being able to start any Linux binary is very useful. Especially when you want to show some real-life examples with your API.
> Can't you just run it in a container or WASM in the browser?
Great thing about VMs is the security, quick snapshotting, and resource oversubscription.
> WASM in the browser
I personally love WASM and am very excited about it. There are however a lot of use-cases where WASM doesn't cut it. Having full environments with a file system and being able to start any Linux binary is very useful. Especially when you want to show some real-life examples with your API.
>There are however a lot of use-cases where WASM doesn't cut it.
>Having full environments with a file system and being able to start any Linux binary is very useful.
https://humphd.github.io/browser-shell/
That said, not practical if the OS image needs to be huge.
>Having full environments with a file system and being able to start any Linux binary is very useful.
https://humphd.github.io/browser-shell/
That said, not practical if the OS image needs to be huge.
RunKit provides this functionality and it’s more or less instant (every version of every package on npm is already pre-installed, you won’t feel the boot up time, just the code in question’s actual execution time). Also, it’s free and has been free since it was introduced about 5 years ago. The code lives on your site so the “degraded experience” if we’re ever down is just “falljng back” to the unrunnable code. Try it yourself and see if the speed is acceptable: https://runkit.com/docs/embed
Hey Francisco, thank you for building RunKit!:)
We have goals on our roadmap which will make the experience much better and near instant. The time and our execution will tell.
We have goals on our roadmap which will make the experience much better and near instant. The time and our execution will tell.
Example integrations aren't loading, I'll check later. This is more or less exactly what we intend to build into our docs. I would like to see pricing.
We currently extract all of our docs snippets at build time, run them, and most importantly put them through automated testing to make sure they never accidentally break. We then capture the output as static content for display. I would still want to do that, including capturing output so the results loads instantly with the page. But we have also wanted to add live editing as an enhancement.
We currently extract all of our docs snippets at build time, run them, and most importantly put them through automated testing to make sure they never accidentally break. We then capture the output as static content for display. I would still want to do that, including capturing output so the results loads instantly with the page. But we have also wanted to add live editing as an enhancement.
> Example integrations aren't loading
We are having a bit of traffic on our shared server sorry about that one. The playground demo from Banana.dev should load in about 20 seconds [1].
The pricing is currently custom based on our customer needs.
I'd love to chat about your use-case if you are up to it, can you shoot me an email vasek at usedevbook.com?
[1] https://app.banana.dev/docs/carrot
We are having a bit of traffic on our shared server sorry about that one. The playground demo from Banana.dev should load in about 20 seconds [1].
The pricing is currently custom based on our customer needs.
I'd love to chat about your use-case if you are up to it, can you shoot me an email vasek at usedevbook.com?
[1] https://app.banana.dev/docs/carrot
While Sandpack has a documentation, this site only bears a sign-up link. You won't get my email prior to buying your product. And to buy it I would to read much more about the how's and what's upfront.
https://app.banana.dev/docs/carrot?ref=navmenu take a look at this customer to get a better sense of how the product works :) No sign-up required.
Is there a way to declare the code in the backend, instead of the frontend?
Declaring the code in the frontend and having the VM execute whatever comes from it is asking for serious abuse.
Declaring the code in the frontend and having the VM execute whatever comes from it is asking for serious abuse.
Yes! You can predefine the whole VM with our CLI [1] via a simple Dockerfile [2]
[1] https://github.com/devbookhq/devbookctl
[2] https://github.com/devbookhq/devbookctl/blob/master/example-...
[1] https://github.com/devbookhq/devbookctl
[2] https://github.com/devbookhq/devbookctl/blob/master/example-...
So how would I create documentation for native GUI apps, or mobile ones, in such scenario?
Usually most of these tools seems to stick with the easy cases, POSIX CLI or Web.
Usually most of these tools seems to stick with the easy cases, POSIX CLI or Web.
how about going the opposite way, while staying in your code editor you can interact with some documentation that guides you to integrate with their code
Stay tuned to what we are building:)
Do you think you will use web-assembly to leverage front-end compute power?
And what to do about those darn crypto miners?
And what to do about those darn crypto miners?
Howdy - founder of Loom here. Cool project. Thank you for recording with us!
Thank you Vinay! We recorded a lot of personalized demos with you guys :)
I'm Vasek, co-founder, and CEO of Devbook [0]. Devbook is an SDK that you add to your docs website and then every time a user visits your dev docs, we spin up a VM just for that user. The VM is ready in about 18-20 seconds. We haven't had enough time to work on optimization but from our early tests, we are fairly confident we can get this to about 1-2 seconds.
In the VM you can run almost anything. Install packages, edit & save files, run binaries, services, etc.
You as a documentation owner have full control over the VM. We give you full access to filesystem, shell, stdout, and stderr. You don't have to worry about any infrastructure management. It's just one line of code on your frontend.
On the backend, the VM is a Firecracker microVM [1] with our custom simple orchestrator/scheduler built on top that just gets the job done. We chose Firecracker for 4 reasons:
* (1) the security with a combination of their jailer
* (2) its snapshotting capabilities
* (3) quick booting times
* (4) option to oversubscribe the underlying server resources
This allows you to create a whole new set of interactions between your dev docs and a developer visiting the docs. We've had users building coding playgrounds [2] to show how their SDK works or adding embedded terminals to a landing page [3] to show how their CLI works.
The way Devbook works is that you use our frontend SDK [4] on our website. The SDK pings our backend and we boot up a VM. The VMs are ephemeral and get destroyed after a while of not getting pinged. You can predefine what the VM filesystem will look like through our CLI via a simple Dockerfile [5]. We also have an open sourced UI library for components like terminal, file system explorer, or code editor [6].
The need for Devbook came from our own frustration with dev docs. It has always felt strange that dev docs contain so much code but none of it is actually runnable. You as a developer have to set up full environments to see how the API works and get a deeper understanding.
We are very early so we don't offer self-serve for now. A bit of manual work is still required when we are onboarding new customers. We are looking for some specific use-case that would make our go-to-market strategy much easier. It feels like the product we offer is way too general. We basically say "here's a whole computer, have fun".
I'd love to know what you think about it. I'll hang out here and I'm happy to answer your questions!
[0] https://usedevbook.com/
[1] https://github.com/firecracker-microvm/firecracker
[2] https://app.banana.dev/docs/carrot?ref=navmenu
[3] https://runops.io/
[4] https://github.com/devbookhq/sdk
[5] https://github.com/devbookhq/devbookctl
[6] https://github.com/devbookhq/ui