[HN Gopher] Show HN: Add live runnable code to your dev docs
___________________________________________________________________
Show HN: Add live runnable code to your dev docs
Hi HN community, 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
Author : mlejva
Score : 65 points
Date : 2022-04-12 16:38 UTC (6 hours ago)
(HTM) web link (www.usedevbook.com)
(TXT) w3m dump (www.usedevbook.com)
| michaeljelly wrote:
| 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.
| mlejva wrote:
| 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.
| JacobDotVI wrote:
| This seems like a great alternative to passing around postman
| collections separate from documentation
| mlejva wrote:
| 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?
| dsmmcken wrote:
| 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.
| mlejva wrote:
| > 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
| madduci wrote:
| Isn't this something similar to Jupiter Books, where you can have
| executable code?
| mlejva wrote:
| 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/
| encryptluks2 wrote:
| 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.
| mlejva wrote:
| 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.
| mimsee wrote:
| 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
| mlejva wrote:
| Thank you. I'm a fan of Sandpack and CodeSandbox:)
|
| The dev docs future looks exciting!
| davej wrote:
| 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?
| mlejva wrote:
| 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.
___________________________________________________________________
(page generated 2022-04-12 23:01 UTC)