Tutorials in Livebook

[woutdp]

Tutorials

I'm interested in building tutorials in Livebook that gradually introduces you to new concepts as you go along targetted towards beginners. Not necessarily Elixir beginners, but for example Ecto beginners. My current interest is seeing if it's possible to make a tutorial for Ash as I think that's where its documentation is lacking. But the tutorial feature should be generalizable to any concept inside and including Elixir.

This could be a great addition to any Elixir package that wants to introduce a tutorial. Something that's easily importable into a local Livebook to get you started.

I would maybe want to develop these features, but before I can start on it I want to align with the Livebook team so there's a clear vision for this.

What is a tutorial?

A tutorial is not a how-to. How-to's are already possible in Livebook. Tutorials serve the purpose of teaching beginners to get familiar with whatever you're trying to teach them. How-to's show you how to do a certain thing.

From the diataxis framework on documentation:

Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are learning-oriented.

How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented.

2 great examples of tutorials are

• Svelte's tutorial
• Exercism

Elements of a tutorial

• A description of what you need to do.
• An editor where you can enter your solution.
• A way to verify your solution, either by just showing the correct solution or by running a test suite.
• Each individual tutorial is isolated and doesn't import code from the previous tutorial.

Why I think Livebook is great for tutorials

Livebook already allows you to run code, write markdown, divide into sections and import packages in a very accessible way. Accessible is the key word here.

In addition it's great for collaboration, allowing for teachers to edit the same code the student is editing.

Why can't we do this already

I see a couple of blockers. Some of these might be possible already, please let me know if that's the case.

• Markdown and sections titles are not lockable, allowing students to edit them. This is not a big deal, but a beginner might be confused by this trying to edit markdown code examples instead of a code block. Some sort of 'soft' lock where you can unlock if you want, but by default it's not editable should be sufficient. Another way of thinking about this is to add soft guardrails that you can disable if wanted.
• A way for code blocks to be invisible (with the possibility to make them visible). This can be used for writing tests. With Kino it should be possible to wire up a button to run the tests. Another ability with this is having invisible code blocks showing the solution code in case the student gets stuck, but hiding them by default.
• Is it possible for other code blocks or kino forms to edit previous code blocks? This way you can have a 'Show solution' button under the input code block that replaces the code with the solution code.
• I think a horizontal layout is preferable, instead of the livebook vertical layout. It's not a big blocker but it's nicer to be able to read and solve at the same time, without having to scroll.
• Divide sections on seperate pages. This would allow you to tackle 1 tutorial at a time, and have some 'next section' button without overwhelming the student. Again when developing for beginners, you want to make it as easy and clear as possible. You can technically already achieve this by having 1 notebook per tutorial.

Features could either be native to livebook, or with external packages like kino/smart cells or a combination of both.
Some of these features might be possible to fix at the same time with some overarching concept, or need to be introduced step by step.

Next steps and questions

• First of all, is this something the maintainers of Livebook would support?
• And if so, what kind of solution would you propose and be fine with? It might be possible with new features that are not dependant on a 'tutorial concept'. Livebook has presentation mode, code zen mode, maybe there's room for a tutorial mode that shows a horizontal layout? Personally I like the idea of thinking about individual features, that when combined give you the power to create a full tutorial, but by itself are not tutorial specific.

Actions

If a conclusion is reached I might be interested in developing these features myself. Either in an external package that integrates nicely with Livebook, or with core features of livebook, depending on how the discussion goes. Before I start on it I want to see if there's interest in the idea at all, and how to approach the idea.

[josevalim]

Hi @woutdp!

Have you seen this talk? https://www.youtube.com/watch?v=glPx8gcu-ek - Brooklyn already has some "kino" components which can be used for teaching. If any are missing, you can implement the remaining Kino components yourself and you don't need to wait for the Livebook team. This would definitely be the preferred route. So I will comment on the Livebook changes.

Markdown and sections titles are not lockable, allowing students to edit them.

I am unsure we would add something along these lines. You will probably need to spend the first lesson explaining what is Livebook anyway, so that can be a quick note. :)

I think a horizontal layout is preferable, instead of the livebook vertical layout.

Honestly, I am not sure. All notebooks I know are vertical and I think we cannot assume horizontal is enough for everyone as I don't think you will have enough space on laptop or low-resolution screens.

We do want to support the idea of canvas in the future, where you can align outputs in any way you want, but the canvas is a separate window/horizontal pane outside of Livebook's main flow.

Divide sections on seperate pages.

Then it is best to use separate livebooks. You can have one lesson per directory with multiple liveboks. You can link between them, in order to keep the flow.

Good luck and let us know how it is going!

[woutdp]

Thank you @josevalim, that video by Brooklyn is exactly what I was looking for! I'll try to go that route, I think it will get me to 100% of the features I was envisioning.

That canvas features sounds promising and more featureful than what I was thinking of.

Just to give you an idea of what I was envisioning with horizontal styling, I copied one of Brooklyn's notebooks and made an altenative layout in photoshop.

Before

After

I would still narrow the text a bit so there's more space for the code, if the canvas feature supports something like this that would be cool!

Smaller screen sizes are an issue though like you said, but making it responsive should fix that. Like only showing on larger screens with the feature enabled in your personal settings. Just throwing out ideas in case you think it's useful.

In any case I'll look into Brooklyn's solution and I'll share any interesting findings here :)

[josevalim]

Awesome. Regarding the mock-ups, it would be code on the left, outputs on the right. :)

[woutdp]

Wanted to share some progress, developing a tutorial for Ash: https://github.com/woutdp/ash_tutorial

So far it has been fantastic!

One thing I'm missing is a way to make components out of blocks. For example, I have a navigation block I add to the top and bottom of the livebooks. I divided every tutorial into one Livebook like suggested, so this allows for quickly going to the next tutorial. Another one is a 'Show Solution' block. Could be nice to not have to repeat myself in those instances. It's not such an easy problem to solve I think but wanted to mention it just in case a light bulb goes off in your head :)

Besides that it's really great. Also loving the Run in Livebook badge, works great!

[NduatiK]

I've looked into how you are rendering the navigation block. If you are willing to make provide a mix project alongside the tutorials, you can create a package that renders out your home components using markdown.

The module would look something like

defmodule KinoAshTutorial.Components do
  def navigation(home_url, back_url, forward_url) do
    Kino.Markdown.new(
      """
      Your HTML
      """
      )
  end
end

[woutdp]

Just wanted to chime in again.

There's 'Code zen' and 'Presentation' mode already present, I was wondering if there is room for more another mode.

I want to have a mode that only allows reading markdown, running and editing codeblocks. Disallowing the ability to edit markdown, or add new blocks. For example, (although I discourage it in my tutorial) when trying to copy markdown, I often find myself double clicking certain words to select them, which opens up the editor. When user testing it with an experienced Ash user, but an unexperienced Livebook user, they were seeing the '+code +block +smart' in between blocks, which isn't relevant for following a tutorial and confused them just a little bit.

Not sure what to call this mode.

This is sort of an alternative for the locking feature you're not excited about :) maybe an all encompassing mode could be more along the lines of something you'de be willing to support? I'd be happy to add the mode myself, but before I start working on it I'd want to make sure it fits with the direction Livebook is going.

The argument that people should just learn livebook is valid though. It might take 5 minutes to learn. But nonetheless it is a barrier. A good example of reducing barriers is the 'Run in livebook' button, which is excellent! No need to manually clone a git repo is one of those things that just reduce the amount of pain a user has to go through.

Philosophically speaking, markdown is for reading and structure only. When making a livebook for other people, users will seldom have to edit the markdown. They're mostly expected to read the markdown, read/execute/edit the code. But the markdown should generally stay the same, as it serves to teach/guide/explain. I think this is true for most usecases, not just for tutorials. Code on the other hand should be edited quite a lot more.

It's also a 'creating' vs 'using' livebook sort of thing.

• When creating, the current mode is great.
• When using existing livebooks, some of it gets in the way

Anyway just wanted to chime in, might be more food for thought!

Also saw some of your Livestream, I'm excited about the doc test feature you're working on! Could be the goto method of including tests inside tutorials :)

[jonatanklosko]

For example, (although I discourage it in my tutorial) when trying to copy markdown, I often find myself double clicking certain words to select them, which opens up the editor.

@josevalim ftr I would be totally fine with dropping double click :)

We want to add more options for the view in #1890, though it's something the end user would need to adjust on their own either way. We could have an option for insert buttons, but I can imagine some users may want to add cells just to have a separate piece of playground. If that's confusing, you could include a note in the tutorial that they can insert cells, but generally don't need to, rather than hide the feature altogether (since they can insert with keyboard shortcuts anyway); this way they can get more accustomed to the tool for long term.

[jonatanklosko]

@woutdp ftr #1937 drops the current double-click behaviour :)

[woutdp]

Custom mode sounds interesting, I'll wait for that feature in any case to see if it fits my usecase :)

Happy to see double-click to edit behaviour being dropped, I think that one is a big one new users, as even after working with Livebook for a while now I still catch myself double clicking while wanting to copy paste

Thank you @jonatanklosko!