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

11–20 of 26 posts

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#11

Post by noworriesnate »

leephillips wrote: post #10
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.

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.

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#12

Post by leephillips »

noworriesnate wrote: post #11
leephillips wrote: post #10

Earlier quoted context omitted.

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

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#13

Post by noworriesnate »

leephillips wrote: post #12
noworriesnate wrote: post #11

Earlier quoted context omitted.

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.

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#14

Post by leephillips »

noworriesnate wrote: post #13
leephillips wrote: post #12

Earlier quoted context omitted.

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.

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#15

Post by peterwwillis »

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

Re: Docable: Literate Runbooks and Interactive Tutorials from Markdown

#19

Post by chrisparnin »

filipsch wrote: post #17

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.

Post reply on HN