Split tutorial into smaller pieces to make learning easier

[mbrukman]

Currently, the Jsonnet tutorial is a single long page with all of the functionality. It doesn't have a table of contents, or step-by-step mode, which means the ways to consume it are:

• scroll through the whole thing, top down
• search for items of interest via Ctrl-F

As an alternative, let's consider A Tour of Go, which provides step-by-step introduction to the language, with a live try-it-in-your-browser evaluation. Even if that goal is hard to reach in one step, the following incremental improvements would help:

1. create a sticky table of contents on the left that show available modules, that link to the appropriate part of the page
2. create a separate page per tutorial element, so each subpage is short and easy to consume (with next/previous navigation)
3. finally, add a scratch pad for live evaluation, like in the Go tour, for folks to try it out in context

Thoughts?

[sparkprime]

It was on my TODO list at some point to add a table of contents.

What do you mean a scratch pad? Every pane is editable and there are suggested modifications to try in the tutorial text.

[sparkprime]

I don't think you can do a Go Tutorial style next / previous without ensuring that each page fits on the screen. However breaking it up into multiple pages and making those pages easy to navigate would definitely help.

[gburiola]

Just providing an alternative point of view.
I actually like the single page tutorial and use it frequently with CTRL-F

However I've been using jsonnet for a while, so my use is mostly to find examples for ideas I have in my head while writing jsonnet code.

a TOC or left pane navigation would certainly help though.