google / google/jsonnet

Split tutorial into smaller pieces to make learning easier

Open
#526 3 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Jsonnet
Stars
7.6k
Forks
475
PR merge metrics
No merged PRs in 30d

Description

Currently, the [Jsonnet tutorial](https://jsonnet.org/learning/tutorial.html) 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](https://tour.golang.org/), 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?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.