Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Docable: Literate Runbooks and Interactive Tutorials from Markdown

github.com

Post reply on HN
Print view View original

1–10 of 26 posts

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#3

Post by Addono »

Chris this is so cool! Earlier this year I was thinking about doing the same thing, mostly for making interactive CLI tutorials - similar to the Git tutorial you have in the examples. Then I tried with Jupyther notebooks, but it feels quite limited, and they are not as easy to work with as Markdown files.

I followed the installation instructions and it works super well! [The Gifs in the README already look promising, but it still lacks the empowered feeling you have when interacting with it.] There seem to be some rough edges, e.g. I bricked my session when enabling Docker probably because Docker wasn't available, but overall it all works super well.

Some small things w.r.t. presenting the project/idea: - I nearly clicked away because there was no quick demo, merely pictures. In part because I scrolled over the install instructions - which could be fixed by a table of contents, but also because cloning and installing is quite a barrier when you still haven't seen much from the product. - The website of ottomatica have some buttons which don't seem to do anything.

Anyhow, out of curiosity, what are your plans with it? I noticed it was an academic endeavor, are you planning on commercializing it and/or building a company around it?

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#4

Post by chrisparnin »

Addono wrote: post #3

Chris this is so cool! Earlier this year I was thinking about doing the same thing, mostly for making interactive CLI tutorials - similar to the Git tutorial you have in the examples. Then I tried with Jupyther notebooks, but it feels quite limited, and they are not as easy to work with as Markdown files. I followed the installation instructions and it works super well! [The Gifs in the README already look promising,…

Thanks for trying it out. We have a bit of work to make bootstrap process easier.

We have a limited set of notebooks published online to demo how they work. For example:

* https://docable.cloud/chrisparnin/examples/basics/script.md

* https://docable.cloud/chrisparnin/examples/tutorials/Git.md

Right now, we're using the notebooks to build better lecture materials + workshops, especially for my DevOps course: https://github.com/CSC-DevOps/Course

We've seen some interest in having support for live documentation + OneOps (simple runbooks for one-off devops tasks), so we'll probably continue to explore this more.

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#6

Post by chrisparnin »

zimbatm wrote: post #5

This looks great! I've been building something similar[1] but it only supports bash as a language. Looking forward to try this out! [1]: https://github.com/zimbatm/mdsh

Nice! I like the "link includes" feature. Funny, because we're displaying the terminal results, we've had the opposite problem, where we need to get and process the ansi-escape codes, so we get colors, and proper formatting, etc.

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#8

Post by sramam »

this is really cool. Looking at the rest of the stuff you have built with ottomatic, wonder if you'd consider getting this to work with something like repl.it.

That'll be really cool - to have a(n almost) one-click live demo framework.

Very nicely done. I'll be trying this out for my product demo as soon as it's ready.

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#9

Post by noworriesnate »

This is really, really well thought out! I've wanted to build something similar for a while, but didn't have the time.

This feels like what Jupyter notebooks, RMarkdown, Observable could have been if the designers had been focusing on multiple programming languages.

I really like that it supports Javascript in the browser and server-side execution.

Edit:

The big drawback for putting complex code in notebooks is that you can't debug it in your IDE. This feels like it could be a standard notebook format supported by lots of IDEs so you can debug scripts in many different languages.

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#10

Post by leephillips »

noworriesnate wrote: post #9

This is really, really well thought out! I've wanted to build something similar for a while, but didn't have the time. This feels like what Jupyter notebooks, RMarkdown, Observable could have been if the designers had been focusing on multiple programming languages. I really like that it supports Javascript in the browser and server-side execution. Edit: The big drawback for putting complex code in notebooks is that…

The acronym “jupyter” is a mashup of the names of multiple programming languages.
Post reply on HN