Livebook Formatting

[djcarpe]

Intent

To reorganize the livebook's as partially complete exercises to be more engaging and educational.

Example

From the blink exercise.

Instead of having a linear "button clicking" example, we would structure the markdown as instructions, and the elixir code blocks as implementation.

This type of explanatory section would change as follows:

--- Now we will create a connection to that GPIO pin and set it as an :output.
--- '''elixir
--- {:ok, led_output} = Circuits.GPIO.open(led_pin, :output)
--- '''
+++ Complete opening the LED pin that we just matched on, match it to a variable, setting it as an output.
+++ If you need more help, uncomment `hint gpio_open`
+++ '''elixir
+++ {:ok, ?} = Circuits.GPIO.?(led_pin, ?)
+++ # hint gpio_open
+++ '''

Hint would be a separate defmodule or map of key/values that we can store guidance on completing each exercise. I'm not sure if embedding this inside the same repo or making this a poncho project would work best.

We could even go a step further and implement schematics as the instructions for more advanced books in the future.

Background

I've been really enjoying learning Elixir and all the communities built around it. A coworker actually turned me onto elixir after we spent some time discussing Rust and building a community for it in our corporate culture.
One of the most effective mechanisms for teaching and learning I've seen in a language so far is the Rustlings project.

We have that same informational delivery system with livebook and this could be a great opportunity instead of sharing how to blink an LED we'd be teaching how to blink an LED.

[fhunleth]

I definitely like this idea for structuring tutorials. This also mirrors many hands-on training classes that I've liked.

I feel like I need to bring this up. I'm slowing innovation down if all changes and discussion has to flow through me - even if I take the strategy of assuming they work and clicking approve on all PRs.

For example, unit testing the existing Livebooks is not ideal. I currently manually click an evaluation button low on the page to spot check if the page still works. That's really tedious and it's causing me to think how this thing scales. Making Livebooks intentionally not work without modifications seems like it will increase this burden.

It should be possible for someone to build out an awesome set of tutorials and distributee them on their own. I realize that including materials in this project helps with discovery, though, so I want to be as supportive of this as possible.

Here's what I'd like to propose:

1. Explore the Livebook import feature to see if it's viable for enabling content coming from outside of this firmware image
2. Coming up with a good organization of the samples directory and cleaning up the current content to fit. Perhaps with an "experimental" subdirectory where we stash half-baked ideas so people can still try them even if they don't fit an overall template.

Regarding Livebook import, I haven't tried it out at all. I've been looking at issues with Mix.install since that will eventually hit us, but I don't know where things stand outside of that. Upstream has been really aggressively adding features, so it could be that they've thought a lot about this. If this feature is good then there could be a Nerveslings project that we build out with these.

If importing Livebooks doesn't work well for us, how about creating a tutorials directory to collect this style of Livebook?

If it's not obvious, I still think there's room for the current "read and click evaluate" Livebooks. I find them super useful for quick demonstrations. We should nail down a structure for the samples directory and then organize the current content. I feel like you've looked at way more projects than I have. I certainly don't mind emulating someone else's project.