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

21–26 of 26 posts

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#21

Post by cxr »

chrisparnin wrote: post #4
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://g…

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

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#23

Post by chrisparnin »

cxr wrote: post #21
chrisparnin wrote: post #4

Earlier quoted context omitted.

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://g…

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-…

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.

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#24

Post by mithro »

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!

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#25

Post by Addono »

chrisparnin wrote: post #4
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://g…

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

Post reply on HN