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

[paulinebessoles]

Hey Thiago, thank you for this proposal!

@tkrieck

Remove the blacked-out background to maintain context.

+1 For this, I agree that we should be able to see the rest of the UI, but I also agree with Marius on highlighting the target area (with a border or box shadow), to make sure users understand what elements they should look at.

@tkrieck

Update the visual design add cleaner, sleeker UI elements.

+1

@tkrieck

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

+1, For the step indicator, I wonder if it wouldn’t be better in a footer under the buttons, as it’s not the most important information.

@tkrieck

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

-0, I’m not sure if we need to have three buttons, IMO if the close button is not visible enough we could highlight it. Also, I think we don’t really need the Previous button. We could say in the last step that the user can do the onboarding again by clicking the “Show tour” in the bottom right.

@tkrieck

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

+1 to keep it and put it at the begining. In general, +1 to rethink the order according to what users want to do in priority. IMO, should be something like: 3 - 6 - 7 - 2 - 5 - 4

Regarding the texts, I think we should rework them at each step (making them shorter and clearer), I could work on proposals.

Finally, I’m thinking it could be nice to have some interactions during onboarding, like saying the user to perform actions to move to the next steps:

1. Click on Edit to start modifying the content of a Page
2. Save …
3. Click on one of the tabs
4. Click on a page in the breadcrumb
5. Resize the panel
6. Click the drawer

Wyt?

[tkrieck]

@paulinebessoles

-0, I’m not sure if we need to have three buttons, IMO if the close button is not visible enough we could highlight it.

I will change my proposal a bit and see if we can manage to have only one button.

@paulinebessoles

• Click on Edit to start modifying the content of a Page
• Save …
• Click on one of the tabs
• Click on a page in the breadcrumb
• Resize the panel
• Click the drawer

I like this. But probably, we would need to have the onboarding steps to be triggered in different moments and actions and not sequentially like we have now.

[tkrieck]

@tkrieck

I will change my proposal a bit and see if we can manage to have only one button.

Here are two options following the idea of reducing the number of buttons a bit
1- With the X to close:

2- With the Skip All link (but no X):

Personally, I’m more in favor of the second one because the outcome it’s more clear.

[amilica]

Just saw this thread, most changes look great to me!

I have some general concerns about the tour in itself as a concept and wanted to write them here.

The value of the tour

My main concerns around the tour are:

• the perceived value of the tour,
• its initial usage obstruction level
• how much does it smooth a part of the learning curve.

I almost always skip tours that don’t let me directly interact with the software. I’m sure there are many users just like this, especially when talking about software that people expect to “just work” - knowledge management software is clearly one of them.

Right now, the tour, even with the changes stated here, still doesn’t give a lot of value to new users. Many things are easily understandable either because they have explicit labels or have familiar positions.

I’m thinking we could skip them entirely or just cover them in a very simplified diagram in one modal.

Ideal tour

What people don’t know at first and would probably like to be presented is:

• do we have the same UX patterns for their favorite features
• does XWiki have certain essential settings for their team? if yes, where

This translates into some main functionalities to present…

• How to use macros ( showing “/”)
• How to add extensions
• Some key settings in global admin (customization, rights, etc. - maybe this is a separate tour in itself

What I envisioned for this tour

I’d maybe have at least one more to encourage the user to discover everyhting else in GA, create an AWM and make them aware of the What’s new section

Disclaimer

I know what I’m proposing is a bit different from what the goal of this discussion is ( a bit more oriented towards improving what we have and not creating something new), but I thought I’d still show you a version I thought about for a long time.

[tkrieck]

@amilica

I know what I’m proposing is a bit different from what the goal of this discussion is

And that’s not a problem I welcome any feedback either way. I like your proposal, in fact I encourage you take a look at the one being proposed for Cristal as well Proposal for Structuring Cristal's Onboarding Process since that one shares some of your ideas.

I’ve been analyzing other apps in the meantime and noticed that Onboardings in general have taken a very simplified path lately. Notion just revamped theirs with very basic stuff for user name, photo, some workspace configs but that’s it, they let the user explore quite early in the process without mentioning big things in their feature set, like databases. I wonder if that’s interesting for us as well.

[vmassol]

@amilica

Right now, the tour, even with the changes stated here, still doesn’t give a lot of value to new users. Many things are easily understandable either because they have explicit labels or have familiar positions.

I agree with you Adina!

Oc, the best way is to make the XWiki features more usable, and discoverable by themselves as much as possible.

I also like your proposal topics for a new tour, ie displaying interesting features in XS. Creating AWM apps could also be included. Maybe we need several tours depending if your a standard user or an admin (or have each tour page defines whom they’re are targeting and only display admin tour pages for users who are admins).

I think we could imagine also reusing this for displaying release notes inside XS, ie when your wiki has been updated, display some important information (like new features or important changes of behaviors). It’s more work but could be interesting for the future.

Thank you

[paulinebessoles]

Nice proposal Adina!

@vmassol

Maybe we need several tours depending if your a standard user or an admin (or have each tour page defines whom they’re are targeting and only display admin tour pages for users who are admins).

I also think we would need this, to not display options users don’t have access to.

@vmassol

I think we could imagine also reusing this for displaying release notes inside XS, ie when your wiki has been updated

+1

[mleduc]

@amilica

What I envisioned for this tour

Thanks for this interesting alternative proposal.

If I understand correctly, you propose to have a screenshot on each step.

I think that’s a risk because the theme of the screenshots will not always match the one from the instance (let alone the maintenance cost of keeping the screenshot up to date after each release).

[tkrieck]

Hi everyone, just to let you know that I’ve started a topic more specific to onboarding in general (not just the Tour App) here: Proposals for improving the Onboarding Experience

[vmassol]

@vmassol

I think we could imagine also reusing this for displaying release notes inside XS, ie when your wiki has been updated, display some important information (like new features or important changes of behaviors). It’s more work but could be interesting for the future.

-1 to myself after more thoughts Using the Notifications area with a link to the RN page on xwiki.org feels like a much simpler and less intrusive option. See also Proposals for improving the Onboarding Experience - #14 by vmassol