The Wayback Machine - https://web.archive.org/web/20200908053738/https://github.com/google/jsonnet/issues/526
Skip to content

/ jsonnet

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Split tutorial into smaller pieces to make learning easier #526

Open
mbrukman opened this issue Jun 12, 2018 · 3 comments
Open

Split tutorial into smaller pieces to make learning easier #526

mbrukman opened this issue Jun 12, 2018 · 3 comments
Labels
documentation

Comments

@mbrukman
Copy link
Member

@mbrukman mbrukman commented Jun 12, 2018

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
Copy link
Member

@sparkprime sparkprime commented Jun 12, 2018

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
Copy link
Member

@sparkprime sparkprime commented Jun 12, 2018

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
Copy link
Member

@gburiola gburiola commented Jun 12, 2018

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation
3 participants
@sparkprime @mbrukman @gburiola
You can’t perform that action at this time.