I really like the idea !

In order to properly implement this, we need to:

• review existing javascript guided tour libraries and pick one that will fulfill our needs
• find a way to configure the UI elements we want to highlight and explain in the guided tour, in order to easily add new guidelines as new browsing features get landed

Ok, this is the way we'll go, merging in T3196 that is now obsolete.

The guided will allow to showcase all the features packed into the interface of the archive view: permalinks, code fragment selection, visits, history, save code now, download, etc.

The intro.js library seems pretty simple to use, can be configured through JSON, can provide guided tour but also UI hints and is highly customizable.

This is the first library I reviewed but it looks like a good candidate for our needs.

Bootstrap Tour also looks great, simple to use, easy configuration, also a good candidate.

chardin.js library is also interesting, it creates a simple overlay to display instructions on existent elements instead of using popups.

So I did some first tests using chardin.js but the result is not really conclusive.

Let's try Bootstrap Tour now.

Turned out Bootstrap Tour is not compatible with Bootstrap 4.x but hopefully it exists a fork Bootstrap Tourist that supports it.

The first results are quite nice and integrate nicely with our custom Bootstrap theme, see samples below.

I will also test intro.js tomorrow to check which library is better.

So I have played with intro.js and it is clearly the best guided tour library that I have tested so far:

• AGPL license
• nice display and smooth animations
• JSON configurable
• no Bootstrap dependency (CSS framework agnostic)
• well maintained

Below are some screenshots of the result.

So we have a winner here.

In T3202#65029, @anlambert wrote:

So we have a winner here.

Very nice! It's a go for me :-)

After some brainstorming on the subject, I was thinking to launch the guided tour through the Help link in the left sidebar and thus dump the Help page.

As the browsing features to detail span across multiple pages, we should declare a configuration that defines a sequence of URLs to visit and the different UI
components to highlight in each page.

Tour should also be dynamic or require some user interactions when needed, notably:

• for the SWHIDs tab, first highlight the tab anchor on the right, then expand the tab and highlight its content
• for the source code highlighting feature, highlight a line number and asks for the user to click on it, then explain how to select a range of lines

Those kind of dynamic tour behavior should be feasible by using an intro.js event handler.

In T3202#65222, @anlambert wrote:

After some brainstorming on the subject, I was thinking to launch the guided tour through the Help link in the left sidebar and thus dump the Help page.

Is the Help page linked from some other place? (i.e.: are we risking 404s if we dump it?)

As the browsing features to detail span across multiple pages, we should declare a configuration that defines a sequence of URLs to visit and the different UI
components to highlight in each page.

Tour should also be dynamic or require some user interactions when needed, notably:

• for the SWHIDs tab, first highlight the tab anchor on the right, then expand the tab and highlight its content
• for the source code highlighting feature, highlight a line number and asks for the user to click on it, then explain how to select a range of lines

Very nice and useful, indeed!

Those kind of dynamic tour behavior should be feasible by using an intro.js event handler.

Great, what would you need to move forward and try this out in staging?

When we have a POC, we can take advantage of the growing cohort of SWH Ambassadors to get a fresh feedback on all this.

Is the Help page linked from some other place? (i.e.: are we risking 404s if we dump it?)

I mean dumping the link not the page but I could move it in the footer to still reach the page.

Great, what would you need to move forward and try this out in staging?

What I can do is enabling the guided tour by configuration. This way we can deactivate it in production
until we got something stable and usable while we can test the feature on staging.

In T3202#65224, @anlambert wrote:

Is the Help page linked from some other place? (i.e.: are we risking 404s if we dump it?)

I mean dumping the link not the page but I could move it in the footer to still reach the page.

Ok

Great, what would you need to move forward and try this out in staging?

What I can do is enabling the guided tour by configuration. This way we can deactivate it in production
until we got something stable and usable while we can test the feature on staging.

Great.

In T3202#65224, @anlambert wrote:

What I can do is enabling the guided tour by configuration. This way we can deactivate it in production
until we got something stable and usable while we can test the feature on staging.

I suggest to have a round of internal user testing. It has been enabled in staging, if I understand correctly, but nobody in the team knew about it. It would be useful to send out a message to swh-devel (the list), saying it is available there, encouraging trying it out, and gather feedback. Then we can either push in production or iterate a bit more if (pertinent) comments emerge.

It would be even better if we could make non staffers play with it and give feedback, but I don't think that's currently doable due to the VPN and stuff. (That's fine.)

In T3202#65229, @zack wrote:

In T3202#65224, @anlambert wrote:

What I can do is enabling the guided tour by configuration. This way we can deactivate it in production
until we got something stable and usable while we can test the feature on staging.

I suggest to have a round of internal user testing. It has been enabled in staging, if I understand correctly, but nobody in the team knew about it. It would be useful to send out a message to swh-devel (the list), saying it is available there, encouraging trying it out, and gather feedback. Then we can either push in production or iterate a bit more if (pertinent) comments emerge.

It would be even better if we could make non staffers play with it and give feedback, but I don't think that's currently doable due to the VPN and stuff. (That's fine.)

Nothing have been deployed so far, I am still in the investigation phase of how to do it properly but I should be able to send a first draft for review at the end of the week.

If we want non staff users to give a try to the tour before official release, we could take advantage of authentication here and activate the guided tour only for users with a dedicated permission.

In T3202#65230, @anlambert wrote:

If we want non staff users to give a try to the tour before official release, we could take advantage of authentication here and activate the guided tour only for users with a dedicated permission.

Please do. We will take advantage of the growing cohort of SWH Ambassadors to get a fresh feedback from real users that are not part of the team, and that come from different backgrounds.

In T3202#65231, @rdicosmo wrote:

In T3202#65230, @anlambert wrote:

If we want non staff users to give a try to the tour before official release, we could take advantage of authentication here and activate the guided tour only for users with a dedicated permission.

Please do. We will take advantage of the growing cohort of SWH Ambassadors to get a fresh feedback from real users that are not part of the team, and that come from different backgrounds.

Ack, the first glance to the tour will then be offered to staff and ambassador users. No need to touch configuration after all.

First version of guided tour has been deployed to production for ambassador and staff users.

Once authenticated in the webapp, click on the Help menu entry in the left sidebar to run it.

Some improvements will be surely needed before offering it to all users, please post your reviews in that task and I will handle the required changes afterwards.

That's awesome! I did not spot any typos.

I'm wondering whether we could simply drop the "Here you can <verb>..." and make it just
"You can <verb>" or even "<Verb>" since the location of where we are is otherwise
already highlighted (that makes the "here you can" redundant).

You did exactly that (use the imperative form) for the "Browse revisions history" help
message. That feels more natural to me.

My 2 cents ;)