XWiki onboarding tour

[tkrieck]

Hi everyone, I would like to talk to you about the onboarding process of XWiki.

Onboarding is one of the most important characteristics of a good product. Done well, it reduces friction, reduces cognitive load and, if done elegantly, users don’t even notice they are being guided.

XWiki provides two primary onboarding processes:

• First-Time Run — triggered on un-flavoured downloads, primarily for system administrators.
• First Time User Experience - handled by the Tour App, aimed at guiding end users through the interface.

This post focuses on the second process: the First Time User Experience. While the first-time run process is essential for admins, improving the Tour directly benefits daily users by helping them adopt XWiki faster and with less friction.

I will separate this proposal in two sections:

• General Issues, for improvements on all steps
• Step Specific Improvements, for specifics, as the name suggests.

General Issues

After analyzing the existing onboarding tour, some issues appeared that could be improved:

1. Darkened Background Obscures Context
   Users lose visual context of the interface beneath. There’s also a flicker when going from one step to the next.
2. No Progress Indicator
   There’s no visual cue to show how many steps are in the tour or which one is currently being viewed.
3. Limited Exit Options
   Users can only skip the tour by clicking the small “X” button, easy to miss, especially for first-time users.

Proposed solution

Here’s how we can make the Tour more appealing and easier to use:

• Remove the blacked-out background to maintain context.
  • Alternatively, if removing the black background is not possible, or undesired we could at least change it to white and make it more transparent so context is not lost.
• Update the visual design add cleaner, sleeker UI elements.
• Add a dedicated “Skip All” button that’s prominent and clearly labeled, serving the same purpose as the X icon.
• Introduce a step indicator to provide a sense of progress and control.

Note: Currently, the Tour App uses bootstrap-tour — an open-source library that hasn’t seen maintenance in over 7 years. Could we migrate to, perhaps, to Intro.js or TourGuide.js?

Changes in context

Individual elements

Step Specific improvements

We can also modify a bit the steps in the default Tour:

01 - Welcome to XWiki

IMO it could be removed as it’s not very specific and provides little useful information.

02 - Breadcrumb

Could be shortened to just the first paragraph, the home icon explanation feels unnecessary as it is a very common UX artifact

03 - Page menu

The same as before, could be shortened to just the first paragraph. Nowadays, the three-dot icon is also very common.

04 - Header

The same as before.

05 - Panels

Proposal for text: “Navigate through wiki pages and applications here”. The text targeting Administrator feels unnecessary as this is an end-user process.

06 - Page content

Feels unnecessary, as it is the whole purpose of XWiki. Also, many users can’t edit pages, specially the home page on a wiki.

If you feel this step is necessary, then my proposal is to show it at the beginning of the process, not in the middle.

07 - Page tabs

Rename to: Auxiliary Information
Proposal for text: “Additional information for the page are shown here”. This is because comments might be disabled for established wikis with new users taking the tour.

08 - Tour complete

Looks fine to me, it reinforces the end of the process and provides a link for more information.

So, to summarize, my proposal for the steps is to:

• Remove steps 1 and 6. Reducing to 6 steps, from 8
• Shorten the text on almost all steps.

---

Thank you all for reading, I welcome any feedback that you might have.
Thiago

[CharpentierLucas]

@tkrieck

There’s also a flicker when going from one step to the next.

That one is probably a technical issue that could be fixed with time spent on it

@tkrieck

Remove the blacked-out background to maintain context.

• Alternatively, if removing the black background is not possible, or undesired we could at least change it to white and make it more transparent so context is not lost.

-0, I don’t really see the point of this one. Isn’t the goal of this tour to force the focus of the user on the few items highlighted?

@tkrieck

Update the visual design add cleaner, sleeker UI elements.

As far as I know, the tour follows XWiki’s theme. I’m not sure what you mean by this.

@tkrieck

Add a dedicated “Skip All” button that’s prominent and clearly labeled, serving the same purpose as the X icon.

+1, it’s always good for accessibility to make things more explicit. What color do you think we should go with for this button? I think the Success color scheme would fit best here. Keeping it grey would make it really low focus, but error or warning colors would be too aggressive given that every user sees this on every wiki.

@tkrieck

Introduce a step indicator to provide a sense of progress and control.

+0 I don’t have a strong opinion on this, if the tour is fast enough it’s not as important to track progress. But implementation should be pretty simple since the tour-step number is already hard coded in the XObject for each step

@tkrieck

Could we migrate to, perhaps, to Intro.js or TourGuide.js?

I didn’t check the libraries, but we need to make sure we can map every functionality we make available via the Tour class in XWiki Standard.
I’m +1 to migrate away from bootstrap tour but I’m not 100% percent sure using another external library would be easier than just implementing it our own way. Dialogs were quite a hassle to setup back in the days, but now CSS and Javascript are more powerful and I believe it’s an option to implement it ourselves (a bit like what we did for the drawer). I’d rather avoid spending time migrating to another external library that will be outdated/abandonned in five years But if we find a project that looks active enough and ticks all our boxes, let’s go!

@tkrieck

01 - Welcome to XWiki

IMO it could be removed as it’s not very specific and provides little useful information.

This made me wonder what the context was when the tour was designed. From a search in our design archive, it seems like the tour was implemented somewhere between 2015 and 2017.
The context was a bit different for XWiki and its average user, the tour content can definitely gain by being updated.

Thanks for starting this proposal!

Lucas C.

[mleduc]

@tkrieck

Note: Currently, the Tour App uses bootstrap-tour — an open-source library that hasn’t seen maintenance in over 7 years. Could we migrate to, perhaps, to Intro.js or TourGuide.js?

No idea which alternative is best. But if bootstrap-tour is indeed unmaintained, +1 to search for an better option.

@tkrieck

The same as before, could be shortened to just the first paragraph. Nowadays, the three-dot icon is also very common.

I’m not 100% convinced. While the three dots are expected to show something, I don’t know if the content of the sub-menu is easy to guess.

@CharpentierLucas

-0, I don’t really see the point of this one. Isn’t the goal of this tour to force the focus of the user on the few items highlighted?

+0 on my end. While having a strong focus on the highlighted element is essential, it feels interesting to also give a glimpse of the surrounding page to help users understand where everything is.

@CharpentierLucas

+0 I don’t have a strong opinion on this, if the tour is fast enough it’s not as important to track progress. But implementation should be pretty simple since the tour-step number is already hard coded in the XObject for each step

I disagree. When at the first step, without a good idea of how many steps are ahead, I’ll personally just skip the whole tour.

Additional question: Did you consider the user experience on small screen? I don’t know if the current experience is ok, or what others are doing. But, seems interesting to think about it.

[CharpentierLucas]

@mleduc

Additional question: Did you consider the user experience on small screen? I don’t know if the current experience is ok, or what others are doing. But, seems interesting to think about it.

Right now we just desactivate it for small screens, but average screens zoomed in gets very buggy really quick. I agree that we should at least think about it for this overhaul

[surli]

@mleduc

@tkrieck

The same as before, could be shortened to just the first paragraph. Nowadays, the three-dot icon is also very common.

I’m not 100% convinced. While the three dots are expected to show something, I don’t know if the content of the sub-menu is easy to guess.

I agree with Manuel on this one: feels like it could be useful to describe a bit the content. For me it’s the same for the hamburger menu: I think we should keep the mention of it (I vaguely remember that back when I discovered XWiki it took me time to find that icon…)

@mleduc

@CharpentierLucas

+0 I don’t have a strong opinion on this, if the tour is fast enough it’s not as important to track progress. But implementation should be pretty simple since the tour-step number is already hard coded in the XObject for each step

I disagree. When at the first step, without a good idea of how many steps are ahead, I’ll personally just skip the whole tour.

Yeah I also think we do need that info.

@tkrieck

01 - Welcome to XWiki

IMO it could be removed as it’s not very specific and provides little useful information.

I’m wondering if instead of that we shouldn’t provide clarification how to replay the tour: so if a user skips it accidentally or want to see it another time they could.

[Simpel]

We made our own tour. (We reordered some elements from drawer to topmenu to dismis the drawer - long ago the drawer was an accessibility nightmare - and show the searchbar permanently - no need to click a magnifiying glass to open the bar.)

Maybe our tour could be an inspiration for adjusting the onboarding tour.

1. This tour provides a brief overview of the user interface and the basic functions of the wiki.

2. Clicking on the $Company logo will always take you back to the wiki home page.

3. The search bar (for searching for articles) is located on the right-hand side of the header. As soon as you type the first three letters, results will be displayed, which you can click on directly. Pressing Enter will open the page with all search results and filter options.

The bell icon opens the notification window with your notifications and options for subscribing to pages.

Clicking on your avatar opens your profile. There you can edit your profile data and configure a few additional settings.

The icon on the far right logs you out of the $Company Wiki.

4. The top menu contains a few pages for quick access.

Under 'Help', you will find the 'Sandbox', for example. In the Sandbox, you can try out all the editor's functions without any risk. You will also find the article on keyboard shortcuts under Help.

With the 'Random Page', you can drift through the wiki and see what others in $Company are working on.

The menu items ‘Recently visited’, ‘My changes’ and ‘My likes’ adapt to your wiki activities. If a menu item is currently missing, then you have not yet been active in that area.

5. The 'navigation' panel represents the structure of the $Company wiki. Clicking on the triangles opens or closes a level, allowing you to work your way deeper into the hierarchy.

All levels and articles function as links here, so clicking on them takes you to the respective level or page.

6. The breadcrumbs allow you to see where you are on the page and navigate within the hierarchy.

You can also click on the small triangles to view additional parallel levels and navigate directly to them.

The {{velocity}}$services.icon.render(‘home’){{/velocity}} button always takes you to the wiki home page.

7. This menu contains page-related actions. With the appropriate permissions, you can edit, create, manage or delete pages.

The button {{velocity}}$services.icon.render(‘more-vertical’){{/velocity}} with the three dots shows further actions such as rename, print and share.

8. This is where the content of the current article is displayed.

Here you can insert text, lists, tables, info boxes and structures to increase our collective knowledge.

If you notice a spelling mistake, please take a moment to correct it.

9. Here you will find additional information about the article.

Comments are a good way to discuss the content of the page or leave small notes.

Here you will also find the file attachments for the article. In addition, page versions can be compared in the history or further page information can be displayed.

10. This concludes the tour of the user interface and the basic functions of the $Company Wiki.

Thank you for taking the time to read this and feel free to recommend the tour to others.

In another [[tour ‘Create article’>>doc:Applications.Wiki.Start tour.Tour Create article.WebHome||queryString=‘startTour=true’]] you can see how to create an article.

At the end, we cannot say how often and for how long the tour is used, as we do not track this information. However, we have received positive feedback from people who enjoyed it.

[tkrieck]

@CharpentierLucas

-0, I don’t really see the point of this one. Isn’t the goal of this tour to force the focus of the user on the few items highlighted?

It should focus the user on a particular area, but without hiding the context.

@CharpentierLucas

As far as I know, the tour follows XWiki’s theme. I’m not sure what you mean by this.

Mostly in the title area, currently it has a background and border making it a bit dated. We can update these styles without deviating from the Standard XWiki visuals.

@CharpentierLucas

+0 I don’t have a strong opinion on this, if the tour is fast enough it’s not as important to track progress.

Mostly to give a hint to the user about the length of the tour. Currently, there’s no way to see if it’s close enough of the ending, and a lot of people may drop in the second or third interactions.

@mleduc

I’m not 100% convinced. While the three dots are expected to show something, I don’t know if the content of the sub-menu is easy to guess.

@surli

I agree with Manuel on this one: feels like it could be useful to describe a bit the content. For me it’s the same for the hamburger menu: I think we should keep the mention of it (I vaguely remember that back when I discovered XWiki it took me time to find that icon…)

The sub-menu is grouping a lot of functionality, so there’s already not much that can be said about it without making the text too big. Perhaps we could just mention something like “You can check more options using the three-dot button”, just to keep it short.

@mleduc

Did you consider the user experience on small screen? I don’t know if the current experience is ok, or what others are doing. But, seems interesting to think about it.

I just assumed it would work the same way, but seeing more responses, it seems that’s not the case. On mobile a slide with the main points is more common though.

@surli

I’m wondering if instead of that we shouldn’t provide clarification how to replay the tour: so if a user skips it accidentally or want to see it another time they could.

That’s indeed more useful than what we have now. Note that when the tour is closed, a little hint appears in the bottom right corner inviting the user to restart the process if desired. I noticed just now that there’s a slight visual bug in its arrow though.

@Simpel

Maybe our tour could be an inspiration for adjusting the onboarding tour.

Thank you @Simpel, for sharing your process here, I’ll sure take a good look at it. But right now I noticed that you invite the user to a second tour on creating articles. This is very interesting, and I wonder if we should have something more contextual on XWiki Standard as well.

[mflorea]

@tkrieck

Remove the blacked-out background to maintain context.

• Alternatively, if removing the black background is not possible, or undesired we could at least change it to white and make it more transparent so context is not lost.

I don’t mind removing the black (semi-transparent) background, but I think we need to highlight the target area somehow. I’m not convinced that the “arrow” used by the tour step dialog is enough. E.g. “Is this step about the Edit button or about the entire row of buttons?” or “Is this step about this panel or about the entire panel column?”

@tkrieck

Introduce a step indicator to provide a sense of progress and control.

The dots / circles are fine when you have only a few steps (e.g. 4-5), but I’m not sure it scales / looks good when there are many steps (e.g. 10) like in @Simpel’s example. Moreover, some users may try to click on a circle to jump to a specific step. I’m wondering if showing “X / Y” (current step / step count) is not easier to understand. In any case, I agree we need a step progress indicator.

@tkrieck

Individual elements

I’m not convinced that the arrows on the Previous / Next buttons bring any value. I think it looks cleaner without them.

Thanks,
Marius