Docable: Literate Runbooks and Interactive Tutorials from Markdown | Hacker News Reader

Docable: Literate Runbooks and Interactive Tutorials from Markdown

github.com

91 pointschrisparnin24 comments

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?

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.

Nice, thanks for sharing the demos. Was sharing it at work and its hard to convince people to install something to try it out.

I was wondering about the commercial side, because I noticed that the code responsible for turning it into a "hosted" notebook was kept outside of the main repo, which seems common in SaaS approached.

Anyhow, using it for teaching is definitely a good purpose! In fact, it's the use case which sparked my interest. At work we give trainings and the training materials [1] are already in Markdown, so making them interactive by merely annotating them seems easy enough.

I'm happy to see these DevOps courses take off, two years ago when I was finishing my bachelors in CS DevOps wasn't even part of the curriculum. Being able to implement algorithms and architect code. Now these courses are everywhere and well up to date with the industries best practices.

[1] https://github.com/eficode-academy

Chris:

Thanks for including the link to your paper[1] in the README. I saved it in my Zotero library and am looking forward to reading it.

Do you have any thoughts or experience with literate programming? What about the role of Docable, versus choosing PDF as the medium for your own paper, versus something like this[2] sort of thing?

1. http://chrisparnin.me/pdf/docable_FSE_20.pdf

2. https://csarven.ca/this-paper-is-a-demo

Living papers are useful vision, but it will take a long way to get there.

Even notebooks still are problematic, for example, this study found that only 25% of Jupyter notebooks could be executed, and of those, only 4% actually reproduced the same results.

http://www.ic.uff.br/~leomurta/papers/pimentel2019a.pdf

One compromise is to evaluate the paper separate from it's artifacts, which are reviewed for availability, reproducibility, and reusability. In software engineering conferences, this is becoming a standard, and while there is a huge burden for reviewers to evaluate these things, I think it does take us in the right direction. So in this case, we also submitted our paper for evaluation for its artifacts.

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.

This is pretty cool but I think it doesn't focus enough on the fact that code which isn't run / tested regularly is most certainly broken.

Some friends at Antmicro developed a little tool called "tuttest" (https://github.com/antmicro/tuttest) designed to enable you to run your code examples on CI. It still needs a lot of work but we are starting to use it in a lot of places. The tool in the future could potentially use a docable compatible metadata for the best of both worlds!

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.

> The big drawback for putting complex code in notebooks is that you can't debug it in your IDE.

I mean, that's one of the many drawbacks. Executing random independent snippets of code in different stages based on multiple variables leads to an insane amount of untestable code paths in an undefined an environment. I hope nobody depends on these for production.

Where it does seem to shine is as a sort of verbose user interface. You could use these to compose user guides to fill out forms and perform the tasks of complex workflows (in theory). But I think the snippets should still be one piece of code so you can actually develop/maintain/use it according to modern best practices.

POD documentation was good for this back in the day. Here's an example of using POD to actually define your program's input: https://metacpan.org/pod/Getopt::Euclid

The acronym “jupyter” is a mashup of the names of multiple programming languages.

Oh didn't realize that! Python always seemed like a first-class citizen but it's been a while since I messed with it so maybe it was how I installed Jupyter.

Well then this is going to blow your mind: https://github.com/jupyter/jupyter/wiki/Jupyter-kernels

Ah right, I should have been more specific. I didn't realize the Jupyter name was a combination of programming language names, but I did know about kernels.

For some reason the non-Python kernels always felt like second class citizens, but I think that might have been because there were other notebooks for languages like R and Scala, and in those notebooks the language integration felt more natural.

Well, Python is privileged in that you have to install it to run the notebook. But when you are using the notebook, all the languages are the same; there’s nothing Pythony about it.

Good stuff! Reminds me of an R package [1] I developed a while ago while at DataCamp that does this specifically for R; it turns static R Markdown documents into interactive playgrounds.

[1] https://github.com/datacamp/tutorial

Yes, we took a lot of inspiration from when my PhD student interned with RStudio:

You can build some cool stuff with RMarkdown and LearnR:

* https://rmarkdown.rstudio.com/

* https://rmarkdown.rstudio.com/docs/articles/rmarkdown.html

One interesting distinction is "tutorials" vs. "lessons"... LearnR and datacamp are much better for _lessons_, where you ask a learner to type in some code and check to see if you got it right, with hidden cells with the appropriate test cases backend.

Excuse my ignorance, but is this essentially like Org-mode just using Markdown?

Yes, see: http://howardism.org/Technical/Emacs/literate-devops.html

This! Thank you, I was waiting for markdown notebooks for quite a while...

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.

Markdown is eating out the (software) world.

Not that I object.

FYI, the word "out" doesn't belong in that sentence and drastically changes the meaning!

Thanks. Good to know

Reply on news.ycombinator.com