Interactive tutorial

[aartaka]

Is your feature request related to a problem? Please describe. Our tutorial is just a piece of text, and quite a dry one at that. It would be nice to actually walk a new user through the things Nyxt can do, interactively. I've tried doing a part of it in ae05569313ed54cbe9916c9c13de8383776ffdde, but that surely is not enough for a full-blown tutorial. There have to be at least several pages covering the basic navigation and some of the cool features in Nyxt.

Describe the solution you'd like My idea is to extend the intro panel buffer with pagination HTML and transform all of our current tutorial into a set of concise pages in this panel covering all the basics of Nyxt.

Describe alternatives you've considered We can rewrite our tutorial and cleanly separate it from the manual (because yeah, I don't like how tutorial is diluting the manual).

Additional context See the attached PDF (because, apparently, GitHub ignores Org Mode as a format for uploads) file for my ideas on interactive tutorial. Those might be quite outdated, as it's a document from 2020, but still, some pointers there.

interactive-tutorial.pdf

#+TITLE:Interactive tutorial ideas

In this document ([[Tutorial]] section), I'll be mostly going over the
existing Nyxt tutorial sections and thinking about ways it could be
made interactive ([[Concept for interactive tutorial(s)]] section).

The +strikethrough+ headers are the ones we won't need in the
interactive tutorial, either because they won't make sense or because
they will be merged with other intuitively connected ideas.

* Tutorial
** Core Concepts
*** Keybindings & Commands
Our Emacs-like style of denoting keys (e.g. =C-x=) can be turned into a
game of pressing keys matching the keybindings. Although it sounds
like an overkill, person having no Emacs/Vim experience can find it
useful.
*** +Quickstart Keys+
Should be explained on examples and not just listed.
*** Buffers
Maybe opening a new buffer (=make-buffer-focus=) or switching
buffers. This, however, is not a feature one uses right away. Browsing
(history, hints, movements in =web-mode=) should go first ([[Navigation]]),
then buffers ([[Buffers tutorial]]).
*** Modes
Same as buffers, should be shown on example. =dark-mode= is a candidate
for showing the concept of modes—it's the mode you notice the visual
change coming from activation of.
*** Minibuffer 
Minibuffer will take part in lots of commands. Therefore, introducing
it as a kind of input area will suffice for the initial tutorial.  A
separated, "advanced" mini-tutorial can be dedicated to all its
features, like history and multiple-selection.
*** Message area
Simple =echo= to show user where message area is. Even this sounds like
an overkill.
*** +Status area+
Status area can be casually introduced while explaining modes and
navigation. 

A recent Powerline article on Nyxt blog can be re-used there.
** Basic controls
The easiest section to make interactive. All the commands are
interactive by their nature.
*** +Moving within a buffer+
Should be shown with examples.
*** +Setting the URL+
I'm not sure it's that important for a starting user to know how Nyxt
completes links. The fact that it completes the URL in a Do What I
Mean fashion is enough. This can be shown in the [[Navigation]] tutorial.
*** +Switching buffers+
Should be explained as a part of [[Buffers tutorial]].
*** Link navigation
This can be explained by JS-full links scattered all over the place,
although this seems to be part of general page [[Navigation]].
*** Using the buffer history
Having a sequence of tree-like branching pages will show an obvious
benefit of tree-like history. Won't it be too long to show, though?
*** +Searching+
Search is not revolutional in Nyxt, except for multi-buffer
search. Mixing it into a multi-buffer part of [[Buffers tutorial]] can show the
benefit of multi-buffer search.
*** Bookmarks
Bookmark file is not particularly interesting to the new user. Should
be in "advanced" tutorial.

Bookmarking commands, on the opposite, are. Again, having a sequence
of bookmarkable pages can show the benefit of tagged bookmarks and a
tag-based search.
*** +Miscellaneous+
Most of the commands listed in this section are either about page
[[Navigation]] (=nyxt/web-mode:zoom-(in|out)-page=,
=nyxt/web-mode:jump-to-heading=) or some cool yet niche features
(=vcs-clone==, =fill-input-from-external-editor=) that the new user may
not appreciate right away. Maybe turning the old-tutorial into a part
of manual, while making a separated interactive one can help both new
and seasoned users?
** The Nyxt Help System
This is a small [[Advanced]] topic.
* Concept for interactive tutorial(s)
** Basic
*** Navigation 
First, we explain keys interactively ([[Keybindings & Commands]], but
we'll need to have a mechanism for fast keymap switching) and explain
why using keyboard is better (that's not always obvious). We also need
to mention that most actions in this tutorial are possible to complete
with mouse.

Then, we load the obstacle course pages that'll require the user to
learn the keybindings by practice:
**** Zooming
Ask the user to set a comfortable zoom level (=nyxt/web-mode:zoom-(in|out)-page).=
**** Basic scrolling
Several screens for scrolling, both vertically and
horizontally. Shouldn't be too long, though. Maybe using JavaScript to
pop messages on scrolling, so that one needs to scroll only half a
screen to see these?
**** Input & link navigation
An input area that user needs to fill. Explaining hints and input (the
problem with pressing TAB in input field can be mitigated by advising
one to press TAB there). [[Link navigation]] is a related
tutorial. Advising some bookmarklets (like link coloring) maybe?
**** Header navigation
Show header navigation by asking to move to the beginning of
tutorial and find some flag (i.e. some data hidden in the text,
maybe some cypher) there, then return to the header about header
navigation and fill it in.
**** Searching
New page. Explain the simplicity of search in Nyxt ([[+Searching+]]) and ask the
user to find a monospace "1" in the table of monospace "l" xD
**** History
New page. Ask the user to go back to the page with controls and input
some secret word in the input field. Then ask them to input the result
of input submission (yet another flag) on this history page. By moving
back and forth in history, one learns the keybindings for this
familiar concept.

This part of tutorial requires internal buffers to have history. Is it
actually that bad to have history for these?
**** Setting a link
Ask the user to call =set-link= and input a =lisp:tutorial-navigation-finish= URL?
**** Final page with thank-you-s
*** Buffers tutorial
Explain what buffers are and how they differ from tabs.
**** New buffer
Ask the user to open new buffer (with some Wikipedia article?) and
switch ([[+Switching buffers+]]) back to the one with tutorial. Adding
that one can use =set-url-new-buffer= to do this in one command.
**** Modes (interactive)
Ask the user to toggle =dark-mode= and explain how modes work in Nyxt
([[Modes]]). Mentioning mode-line ([[+Status area+]]) and mode markers in
it. Is that it?
**** Searching (multi-buffer)
If we're to use Wikipedia, we can ask the user to use multi-buffer
search while in the tutorial buffer, to find some word in this article
and switch to the buffer with article. Some input field for a simple
question on what was read there?
*** Bookmarks, auto-mode, remembering other things?
Re-using =auto-mode= article can come in handy there, but we should be
able to save and apply rules on =lisp= links. For this, we may need to
finally switch to the [[https://webkitgtk.org/reference/webkit2gtk/stable/WebKitWebContext.html#webkit-web-context-register-uri-scheme][webkit_web_context_register_uri_scheme]] so that
the link of internal buffer will actually be the link this buffer
has. Having this, applying =auto-mode= rules will work immediately.

Bookmarks have the same prerequisite -- only the pages with the URL
are bookmark-able.
*** Minibuffer features
If we had support for =<select>= tags completion in minibuffer ([[https://github.com/atlas-engineer/nyxt/issues/1029][#1029]]),
it would've been easy to show, because this is the case fuzzy
completion and minibuffer history shine with effectiveness in.

The second easiest option is to hand-made some =lisp= URLs to call
minibuffer prompts, so that user can see how multiple selection,
history and incremental search can come in handy.

But is that worth implementing just to show how minibuffer works, if
there's a real thing it can be shown on the example of (=<select>= tag)?
** Advanced
Almost all of these are topics that are easier to grasp with text,
because they either have a non-immediate result (like editing [[Files]]
and waiting for page re-loading) or depend on user initiative (like
[[Help]]). Maybe doing manual entries for them, instead of interactive
tutorials?
*** Files
I propose we first write a good detailed article on how we handle
files, to the Nyxt articles page. Then we can integrate this into
manual/tutorial, or even make it really interactive, if we come up
with some interesting ideas on it.
*** Help
I am not sure this needs to be really different from what was there in
[[The Nyxt Help System]]. Maybe make it an intro to manual?

[Ambrevar]

Wow, nice job!

[aadcg]

The document is a bit outdated but the gist of it is still valid.

I don't agree with all proposals, but I don't think this is the right place to discuss it.

The first step would be to open a PR and prepare a document of this kind so that we arrive at a tutorial script/skeleton. Then we can move to implementing it.

I must stress what an interactive tutorial means to me. It's a piece of text that calls the user to actively try things out, thus complementing his theoretical understanding with practice. Going the other way around, i.e. making things interactive while the reader stands passively is a mistake.

I am very skeptical towards the tutorial as a series of panel buffers, since I don't think any meaningful piece of text can fit in there. Also, the user should go through the tutorial in the most common Nyxt interface - the buffer.

[lansingthomas]

this is a phenomenal starting Artyom. -I will mock up some UI iterations for the elements I expect we will need. (keybindings/commands/key legend). -I agree with André's sentiment about the importance of interactivity. (I'm still wrapping my head around how we present the tutorial)

• i think we need to shorten some of what you propose in the basic nav tutorial but let's talk about it over chat friday. well done

[lansingthomas]

Structure and copy is happening in a shared doc (view link). If anyone wants collaborator access please message @lansingthomas or @aartaka

[lansingthomas]

New User Onboarding flow exercise: new user flow.pdf

actionable:

1. we should ensure that two elements {Modifier Key Legend, tutorial binding} are present on BOTH the front page of the manual, AND on the front page of keybindings.

• [ ] modifier-key-legend communicated from front page of Manual
• [ ] tutorial binding (f1-t) is communicated on front page of Manual
• [ ] modifier-key-legend is communicated on List Bindings
• [ ] tutorial binding (f1-t) is communicated on List Bindings

2. How might we prevent brand new (non wizard) users from mashing the Start Search! button and getting lost before they begin?

[lansingthomas]

text content is ready for the first and fourth sections.

1. Buffers
4. Quickstart Bindings

the rest is ongoing

[lansingthomas]

Modes section is good enough for now.

remaining sections for the panel-tutorial are advanced missions and a completion thank you message

[lansingthomas]

Dear Cyber Sillys,

Discussion re: Initiating the new side panel tutorial

Recap: We have four education elements to work with today:

1. two tutorials {longform nyxt:tutorial page, and the new tutorial-panel}
2. , as well as a nyxt:manual page,
3. and list keybindings page

We want to let users choose how to educate themselves, while ensuring that all options are sufficient. A great way to do this is to make sure that all user flows funnel through this new tutorial-panel at some point.

Earlier we {Tom, Artyom} agreed on a few ways to do new tutorial-panel initiation

Primarily: the tutorial-button from the nyxt:new page initiates the tutorial-panel process Ideally we have all of these ways to initiate the tutorial-panel: (for the rationale please see the user flow pdf a few comments above)

1. an autostart for the first few (2) Nyxt App launches
2. the primary tutorial-button on the nyxt:new page
3. link from the top of the nyxt:manual near keybinding information
4. link from the top of the nyxt:list-bindings near keybinding information
5. the keybinding ( f1+t ) from anywhere (I know that this goes to the longform tutorial now, I want (f1-t) to be the side panel because it does not interrupt user's tasks while hopefully resolving some questions -- very important for learning)

How do you want to do the initiation @aartaka? Still good for all the ways?

• [ ] yes
• [ ] yes with conditions (if so please explain)
• [ ] no (if so please explain)

Here are some mockups for the primary method

possible method A

clicking Tutorials presents the two options on click* becomes...

---

---

possible method B

---

---

possible method C

Again, clicking Tutorials presents the two options

My thoughts on the options.

• this choice is important to prevent our users from getting lost in the woods of Greece. We want the tutorial(s) to happen early.
• If anyone has ideas, let's hear them
• I prefer option C (it looks clean, it is easily understood and has precise language, it does NOT use space that would overlap with panels)
• Yes, it is basically an accordion, which is great for saving space and maintaining user freedom.

I mostly want to hear from you @aartaka, but this is a nyxt:new front page thing so it would be cool to get feedback from @jmercouris @Ambrevar @aadcg as well.

Thank youuuuuuuuuuuuuuuuuuu

[jmercouris]

I vote for C!

[aadcg]

I'm not sure about the idea of categorizing tutorials. Instead of having 2 tutorials, I'd suggest having the tutorial as we have now, and naming the new content as "Quickstart".

The new "Quickstart" button could be placed above "Start Searching!".

[aartaka]

I'm on the side of earlier idea that tutorial should be extremely concise and only exist as the quickstart panel, while the rest of documentation should be part of the manual (which we partially duplicate in the longform tutorial anyway).

[lansingthomas]

Oh thats right, we talked about merging the (old)tutorial with manual for advanced missions, and linking the Tutorial button to the panel-tutorial.

My bad, I let an old idea creep back in by mistake.

It should look like this: @aartaka Do you concur?

[aartaka]

I do, yes!

[lansingthomas]

update: @aartaka and I finished the written content today. Meets spec! Huray!

[jmercouris]

Fantastic :-)

Thank you both!

[aadcg]

I think we can close this one. The quick start is done and the new start up page has a button that links to it.

[lansingthomas]

its magnificent -- well done andre