Smoother onboarding experience for newcomers (intro gif, interactive tutorial, etc.)

[ggandor]

The README in its current form mostly considers users coming from Sneak/EasyMotion/Hop, and focuses on the distinguishing features of Lightspeed, in a pretty verbose manner. For people who have never used such plugins, or are even new to Vim itself, the information is too distributed though, and I suspect it is hard to get a quick overview on what the heck is Lightspeed actually doing, and why the fuss.

Related discussion at discourse, which made me think about this issue.

[rktjmp]

I might suggest an interactive walkthrough? AFAIK Lightspeed's highlights are deterministic so you should be able to be pretty explicit in which keys to press. You do need them to be on the exact row-cols though I think, probably need to load some marks to make sure.

Also a highly focused gif is probably good to open with. Something that's

• self documenting (so shows code or actions you have to take, along with the overlay)
• readable (only includes a few lines at a large font size)
• slow (no 180wpm)
• loops in a few seconds (allows user to re-digest them fast)

I.e: https://github.com/rktjmp/highlight-current-n.nvim, https://github.com/rktjmp/lush.nvim (obviously I am biased in liking these here).

The current gifs are both too far/late down the page, and too tiny to view "nicely", I can see something happening and read the key presses but I cant read the text which makes them kinda

I think reading md is much nicer than vimdocs, but maybe you could split your readme up into separate files. I did this recently with Lush, along with abusing the <details> disclosure element to hide large code samples, I think it makes for a less intimidating readme. It does make finding information maybe a bit harder (no ctrl-f) if you know exactly what you want, but each section can now be longer without feeling like other things are getting lost.

[ggandor]

Very good insights and tips... I'm in the middle of implementing a new feature, but will get back to this in due time :)

I might suggest an interactive walkthrough? AFAIK Lightspeed's highlights are deterministic so you should be able to be pretty explicit in which keys to press.

Dumb question: you mean inside Neovim or on a web interface? Terrific idea btw. 😎 (EDIT: Oh, okay, something like the Lush tutorial or ConjureSchool, I get it.)

[ggandor]

https://github.com/ggandor/lightspeed.nvim/issues/102#issuecomment-1029236813

[mikehaertl]

I'd like to expand what @rktjmp said above. When I started to use this plugin I really had trouble to understand all the things going on (and probably still have). So instead of lot of text or GIFs running way too fast I could think of something like:

• A series of screenshots or a slideshow that you can click through in your pace so that the user can ponder on every step and digest what's going on
• Each slideshow should start with the initial situation and make clear where the cursor is and where you want to go to/what you like to achieve (like "Cursor is here --> .... and we want to delete up to here ---> "). Ideally this could be the title image of each slideshow so that we get a visual library of all the use cases.
• After each keystroke there should be another slide with a clear explanation:
  • Which key was pressed and why?
  • What do we see now (i.e. "normal" labels, inverse labels, colors for groups, ...)? What changed (i.e. some labels gone)?
  • Which options do we have (i.e. select label, change group, ...)

There could be a couple of such slideshows, one for each use case / feature.

Apart from that the README could still start with a GIF on top to show off how experts use this to fly around their code. Like an apetizer to get your mouth wet.

[ggandor]

Well, how do you like it? One step to the right direction, I guess.

[rktjmp]

I think you should have more specific use cases, but I don't envy you in trying to cover this. I had a quick go but Lightspeed compresses so much motion and information that it's hard to show without a lot of pictures it feels. Very lucky that video tutorial was made.

I started writing a specific tutorial that was interactive, but since LS will cover some of the text with beacons etc you have to work below the instructions, it didn't feel that intuitive.

When I say specific, I mean something like this, instead of "me, something like frame", say "this frame, right here, this one we are going HERE", don't make the user imagine, tell them the goal and reveal the solution? (You do do this when you get to blue labels.)

(Ignore the colorscheme changing wildly)

At this point I was going to roll back and explain direct jumps when possible but that particular example didn't have one.

Anyway, you get the point probably, of having a more directed "lets do X, here's how we do X, we have done X congratulations". What you have added is an improvement though for sure. I like the bubble-circles.

[ggandor]

it's hard to show without a lot of pictures it feels

Very hard... and we cannot open the README with some mile-long film roll, so this is the best I could come up with for the moment. :)

When I say specific, I mean something like this, instead of "me, something like frame", say "this frame, right here, this one we are going HERE", don't make the user imagine, tell them the goal and reveal the solution? (You do do this when you get to blue labels.)

With this I totally agree though, I might rewrite the text, while keeping the same screenshots.

I started writing a specific tutorial that was interactive, but since LS will cover some of the text with beacons etc you have to work below the instructions

That's cool! What about hacking together a "tutorial mode" (so that you could tell Lightspeed to ignore specific regions in the buffer)? Or using popup windows for the instructions?

The text is pretty great on your slides, I like the notes and instructions very much.

[rktjmp]

I did wonder about a tutorial mode but it can be a lot of code-cost for maybe not much gain and you risk it not matching up with "real use". I did also think about just having two files, that you view in a split (instructions and work area). Probably pop-ups with some custom binds to go prev-next is the nicest solution?

Re the film-strip, I also wondered about hiding steps behind disclosure tags, or maybe you could have a slow gif with a link to another page that has each frame in sequence.

It's still, not great. It gives the impression via the length of words, arrows and frames that lightspeed is super complicated when it's really "type two chars, maybe 3".

[mikehaertl]

Well, how do you like it? One step to the right direction, I guess.

@ggandor I like it. I don't think that it needs to be more verbose.

[ggandor]

It gives the impression ... that lightspeed is super complicated when it's really "type two chars, maybe 3".

Spot on. This is exactly my main source of frustration with all this tutorial stuff. :)

Probably pop-ups with some custom binds to go prev-next is the nicest solution?

Something like this sounds the best indeed. Or just two split windows with synchronized scrolling (in chunks, not linewise). (This latter can use a popup window in a fixed position of course, instead of a normal horizontal split.)

[keiviv]

I also suggest outlining the benefits of using lightspeed vs others in a bolder manner. Both here and at the Awesome Neovim the awesomeness of lightspeed is somewhat downplayed — it looks like one of a bunch.

Maybe using words like "the next generation" would give the newcomers a better picture of the landscape, without sounding dismissive of the alternatives.

[ggandor]

Yeah, we all know that Lightspeed/Leap represent the state-of-the-art in motion plugins, but being too cocky about it can be counterproductive :) Let happy users spread the word instead... That said, the text on Awesome Neovim could indeed be improved.