Proposals for improving the Onboarding Experience

[tkrieck]

Hello everyone,

Recently I have been reviewing how XWiki is presented to new users, both before account creation or download, and after they start using it. The objective here is to consolidate different proposals to improve the onboarding experience, making it clearer, more consistent, and better adapted to different types of users, not only administrators, first-time users but also for frequent users.

We already had discussions about this topic a few times and I’ll link them here for easy access (I’m also linking this topic on those discussions).

• XWiki onboarding tour
• Proposal for Structuring Cristal’s Onboarding Process

Below you will find a set of proposals, organized into two sections: Out-of-app (website experience before download) and In-app (experience after account creation or installation). Each proposal was numbered to make it easier to vote on, comment, or provide feedback.

Note that the content below is a short version of the complete proposal design page, where we have a more complete analysis including competitors benchmark. https://design.xwiki.org/xwiki/bin/view/Proposal/OnboardingAnalysis

Out-of-app (before account creation / download)

Proposal 01: Make the “Try XWiki” button more visible

Why?

• Right now XWiki.org has three buttons that all look the same.
• This splits attention and makes “Try XWiki” less appealing.
  

Proposal:

• Highlight “Try XWiki” as the main/primary button.
• Keep “Download” and “Donate” as secondary options.

Proposal 02: Improve the layout of the Hosted page

Why?

• The page takes too much reading to understand the options.
• Action buttons are far away from their section titles.
• The “Download” option feels hidden.

Proposal:

• Standardize each section into a title and short description.
• Give “Download” the same weight as the other options.
• Suggested order:
  1. Playground – Test instance on XWiki.org, resets daily.
  2. XWiki Cloud – Hosted by XWiki SAS, quick start, stable and secure.
  3. Download – Run it locally or on your own server (requires Java).
  4. MyXWiki.org – Community farm for nonprofits and individuals (no support or uptime guarantee).

Proposal 03: Keep the Playground on the latest version

https://xwikiplayground.org/

Why?

• The Playground is the first experience for many users.
• It should always reflect the latest features.

Proposal:

• Update the Playground each month with the newest release.

In-app (after account creation / download)

Proposal 04: Use slides as the main onboarding method

Also proposed by @amilica here: XWiki onboarding tour - #12 by amilica

Why?

• Slides are familiar, predictable, and less visually complex.
• Keeps everything centered on the screen.
• Easier to follow compared to the Tour app.

Proposal:

• Build an Onboarding App with flows for different user types.
• Each flow is a set of slides with: title, description, optional image, and working area (text, forms, etc).
• Replace the current default Tour app aplication with this new Onboarding app, while keeping the Tour app for other purposes.

Risks:

• Too many slides across flows, particularly for administrators.
• Must allow skipping, but also returning

Proposal 05: Create different onboarding flows (Admins, General users, Returning users)

Why?

• Different users have different needs.
• Administrators need to configure the instance.
• New users need an introduction to the tool.
• Returning users should learn about new features.

Proposal (examples):

• Administrators: Setup basic instance (name, logo, description, visibility, invite users).
• General users: Setup profile (name, photo) and view an introduction with pre-configured pages.
• Returning users: Overview of new features.
• System administrators: Ability to create custom slides.

Example flow for Admins:

Example flow for new users:

Example slide for a new feature

Example flow for a customized onboarding

Open questions:

• How can users switch between flows later?
• Should there be a central onboarding dashboard?

Proposal 06: Make the onboarding app customizable

Why?

• Companies may need to show internal rules, important news, or legal notices.
• Administrators need a way to define this content.

Proposal:

• Each onboarding flow is an XWiki page.
• Each step is a sub-page of the flow.

Proposal 07: Reduce the Tour App steps

Why?

• The Onboarding App should cover general onboarding.
• The Tour app can then be simplified to focus on key actions.

Proposal:

• Use the Tour app to:
  • Show how to restart onboarding.
  • Highlight the Sandbox for safe experimentation.
  • On first edit, point to the “Done” button so users know how to exit edit mode.

To conclude

In summary, the overall intent is to simplify the entry points to XWiki, make it easier for people to get started quickly, and adapt the onboarding process to the needs of different users. At the same time, we want to streamline the Tour app so it remains focused on a smaller number of key actions.

As always, I would very much appreciate your feedback on this. Thanks!

[vmassol]

@tkrieck

Proposal:

• Highlight “Try XWiki” as the main/primary button.
• Keep “Download” and “Donate” as secondary options.

I’m far from sure because:

• The only real option to try leads to a sponsor offer: XWiki Cloud from XWiki SAS. It’s a paying option. So the question is: is it normal/ok to promote a paying solution for an open source community software?
• The other 2 options are not perfect:
  • Playground is reset every day and yo don’t have permissions on it. You cannot install extensions, do any admin stuff, etc. It’s very limited and doesn’t represent what you can do in XWiki IMO. It’s a shallow try experience.
  • MyXWiki.org is not for everyone at all. And it’s a test instance for the XWiki devs, ie not stable, not performant, etc.

The simplest way to try XWiki ATM is to download the Standalone packaging on your computer IMO. The only difficult requirement is that it needs Java installed. The second easiest solution is to use the XWiki Docker image but it requires Docker installed (and that you need some doc to start the DB + XWiki).

[vmassol]

@tkrieck

Standardize each section into a title and short description.

Do you have an example of applying this? Not sure what it means and what would be dropped.

@tkrieck

Give “Download” the same weight as the other options.

What would you show? A button to redirect users to the Download page?

Note that page was supposed to only offer Hosted solutions but since it’s named “Try XWiki”, I guess that could work fine.

@tkrieck

Suggested order:

1. Playground – Test instance on XWiki.org, resets daily.
2. XWiki Cloud – Hosted by XWiki SAS, quick start, stable and secure.
3. Download – Run it locally or on your own server (requires Java).
4. MyXWiki.org – Community farm for nonprofits and individuals (no support or uptime guarantee).

Sounds good.

[vmassol]

@tkrieck

Proposal 03: Keep the Playground on the latest version

https://xwikiplayground.org/

Why?

• The Playground is the first experience for many users.
• It should always reflect the latest features.

Proposal:

• Update the Playground each month with the newest release.

+1, we’ll need to check if the infra maintainers are ok with this or provide scripts to them.

Note that it means it’ll be less stable than the LTS so there’s a small risk but I think it’s worth taking.

[vmassol]

@tkrieck

Replace the current default Tour app aplication with this new Onboarding app, while keeping the Tour app for other purposes.

You don’t mean to keep the Tour app in XS, right?

[vmassol]

@tkrieck

Proposal 04: Use slides as the main onboarding method

Also proposed by @amilica here: XWiki onboarding tour - #12 by amilica

+1

[vmassol]

@tkrieck

Proposal 05: Create different onboarding flows (Admins, General users, Returning users)

I don’t understand how the Admin flow integrates/replaces the Distribution Wizard. The L&F looks very different. I’d have imagine a revamped DW and adding some steps to it.

I’d also have imagined using the DW solution for the non-admin flows.

Do I understand correctly that Proposal 5 uses Proposal 4 for the implementation? If so, where does the DW come in the picture?

@tkrieck

Example flow for new users:

But a new user will have registered and already filled all that info…

@tkrieck

Example slide for a new feature

What’s the process of creating slides for new feature? Where does the info come from? Does it come directly from the Release notes? If not then it seems too much work. We’d need to take into account the case where XWiki is behind a proxy that doesn’t have access to the internet.

Also the features must depend on the user. Luckily we already have that info in the Release notes on xwiki.org. We could imagine:

• By default only showing “High” importance features
• Make it configurable in your users profile so that you can decide to see also other importance features (Medium and Low)

When would it show? In general users log in automatically with “remember me”.

Shouldn’t we use the Notifications feature instead for Release Notes (can’t find where we talked about this), see also:

• Loading...
• Loading...

[vmassol]

@tkrieck

Proposal 06: Make the onboarding app customizable

+1, could be done with the DW too.

[vmassol]

@tkrieck

Proposal 07: Reduce the Tour App steps

Why?

• The Onboarding App should cover general onboarding.
• The Tour app can then be simplified to focus on key actions.

Proposal:

• Use the Tour app to:
  • Show how to restart onboarding.
  • Highlight the Sandbox for safe experimentation.
  • On first edit, point to the “Done” button so users know how to exit edit mode.

-1 from me for now. This seems too much and overlaps with the revamped DW / Onboarding App.

@tkrieck

On first edit, point to the “Done” button so users know how to exit edit mode.

This seems to indicate that we need to fix that button instead of working around it!

@tkrieck

As always, I would very much appreciate your feedback on this. Thanks!

Thx for the ideas and work!

I think it would be great to include a revamp of the Home page in the onboarding topic.

[tkrieck]

@vmassol

I’m far from sure because:

• The only real option to try leads to a sponsor offer: XWiki Cloud from XWiki SAS. It’s a paying option. So the question is: is it normal/ok to promote a paying solution for an open source community software?
• The other 2 options are not perfect:
  • Playground is reset every day and yo don’t have permissions on it. You cannot install extensions, do any admin stuff, etc. It’s very limited and doesn’t represent what you can do in XWiki IMO. It’s a shallow try experience.
  • MyXWiki.org is not for everyone at all. And it’s a test instance for the XWiki devs, ie not stable, not performant, etc.

Note that I am not proposing to change too much on this regard, all options already exist in the XWiki.org website. This item deals only with the diferentiation between primary and secondary buttons. We could point to “Download” as the primary option.

@vmassol

Do you have an example of applying this? Not sure what it means and what would be dropped.

Nothing too fancy. My proposal is just to integrate the visuals a bit better and make the whole block as the touch/click area. Note that I only listed XWiki SAS as the cloud option because right now that’s the only option, if we have more companies again we can take a look at this again.

This is a quick mockup, just to show the idea for these options, the final L&F should follow the XWiki.org standard.

@vmassol

You don’t mean to keep the Tour app in XS, right?

I do, yes. But not in the current format with all the steps, greatly reduced.

@vmassol

Do I understand correctly that Proposal 5 uses Proposal 4 for the implementation? If so, where does the DW come in the picture?

Indeed, prop 5 uses prop 4 method. The thing with the DW is that not everybody sees it. You don’t see it when using the download option, for example. And the DW is much more complex when setting up a new instance. Perhaps some DW steps could be integrated on the onboarding, but I’m not sure about that.

@vmassol

But a new user will have registered and already filled all that info…

This can be a confirmation step, a chance for users to update information if they want to. Perhaps an admin set up the user with missing info, wrong info or no photo. Perhaps users themselves filled in wrong info by accident. Note that nothing will be required, you can just jump to the next step.

@vmassol

What’s the process of creating slides for new feature? Where does the info come from? Does it come directly from the Release notes? If not then it seems too much work. We’d need to take into account the case where XWiki is behind a proxy that doesn’t have access to the internet.

I don’t have an answer for all of these questions. We could drop this from the proposal if you feel it’s going to be much work.

But my intentions were for very high profile features like BlockNote, or the collaborative editor recently released. So not every release would have something like that.

@vmassol

When would it show? In general users log in automatically with “remember me”.

If someone is already logged-in we could show on first time use after an upgrade (and only then). Do we have statistics on the use of the “Remember Me” feature? I’m asking because the default is off

@vmassol

Shouldn’t we use the Notifications feature instead for Release Notes (can’t find where we talked about this), see also:

That’s an option as well. But differently from the onboarding options being proposed, the notification can be always shown, for every release.

@vmassol

This seems to indicate that we need to fix that button instead of working around it!

Yes, if feasible that would be the better choice, then we don’t need this step. But until then we could at least point to the “Done” button.

@vmassol

I think it would be great to include a revamp of the Home page in the onboarding topic.

Yes, this is planned. @amilica is working on it for this roadmap.

[mleduc]

@vmassol

The simplest way to try XWiki ATM is to download the Standalone packaging on your computer IMO. The only difficult requirement is that it needs Java installed.

Slightly off topic, but couldn’t we imagine shipping a standalone package with a prepackaged JRE?

[mleduc]

@tkrieck

This can be a confirmation step, a chance for users to update information if they want to. Perhaps an admin set up the user with missing info, wrong info or no photo. Perhaps users themselves filled in wrong info by accident. Note that nothing will be required, you can just jump to the next step.

It feels like an unnecessary step before accessing the wiki. If the user realizes some information is wrong, we must make sure they find how to change it “the normal way” instead.

@tkrieck

Yes, if feasible that would be the better choice, then we don’t need this step. But until then we could at least point to the “Done” button.

So you propose to use it as a quick patch to temporarily compensate for usability issues?
Are there other scenarios where you’d like to keep the tour?

[tkrieck]

@mleduc

So you propose to use it as a quick patch to temporarily compensate for usability issues?

Yes, I’m not against it, I feel it can be an effective stepping stone towards an ideal solution. It should not be overdone, of course. So more a mitigation feature than a resolution.

@mleduc

Are there other scenarios where you’d like to keep the tour?

I don’t have anything in mind right now. But also, for that to be effective, we would need the change in background proposed here: XWiki onboarding tour so that the context for the user is maintained.

All in all, for me, the Tour App and Onboarding App are complementary to each other and not mutually exclusive.

We can also imagine scenarios of the tour app being used to point to small quality of life improvements in the UI. Small texts like “Your notifications are now here", or “You can start following this page here". These would be useful for users coming from an older version, but not necessarily new ones (is there a way to only show onboarding steps for these users?)

[vmassol]

Just to be clear (in case it wasn’t in my comments above), my POV:

• We shouldn’t develop a new onboarding app. We should instead use the existing DW and refactor it (new screens, make it extensible, improve the L&F, make it appear in more cases than just once for Admins at install or upgrades). We could decide to rename it if the name is a problem.
  • The rationale is that we should have to maintain two apps that do something very similar.
• We should drop the Tour. It’s way too confusing and complex to maintain to have 2 onboarding solutions. Also the premise of Adina’s proposal is that the Tour is not the right solution so I wouldn’t keep it.
• Regarding Release Notes, I think I’d prefer to use the Notifications area and have 1 notification after each upgrade, with a link to the RN page on xwiki.org. That’s simpler to implement and less intrusive than including that in the DW.
• We need a better definition of all the various onboarding flows we’d like to have, using the DW.
• For Admins, we could also consider a DW step suggesting some most used extensions.
• For Admins, we could also have a DW step to define the main config parameters of XWiki (such as the Hibernate configuration).See Loading...
• More generally check Loading... for DW improvements that could be needed in the context of onboarding.

Thanks

[amilica]

@tkrieck

Proposal:

• Highlight “Try XWiki” as the main/primary button.
• Keep “Download” and “Donate” as secondary options.

Strongly agree

@tkrieck

Proposal 02: Improve the layout of the Hosted page

I think the main point is to have it clearly explained what are you getting out of each without reading too much.

• Try XWiki in Playground - limited trial (with no look into Admin actions)
• Try XWiki Cloud - full trial from XWiki SAS with all features (including Admin actions & Pro extensions)
• Download XWiki - full and free acess to the whole project, [license link]
• Account on MyXWiki.org - for non-profit organizations and individuals, no uptime or support warranty, no programming rights

Anything more than that should be added in a collapsable / hidden section.

I’d also think this is the ideal order as it is cohesive with the levels of effort and value the user puts in / gets:

• Playground trial - low effort to sign up, not as much value as the user doesn’t get to see the full product
• Cloud trial - moderate effort to sign up, sees the whole product and Pro features, but for a limited time
• Download & Install - high effort, but gets the whole product for free, forever
• My XWiki org - is an exception and can also be put separate on a line of its own.

@tkrieck

Proposal 03: Keep the Playground on the latest version

Strongly agree, it would be great

@tkrieck

Proposal 05: Create different onboarding flows (Admins, General users, Returning users)

This would be amazing

@tkrieck

Proposal 06: Make the onboarding app customizable

Very interesting, I can see this as a very useful extension

[vmassol]

@amilica

Try XWiki in Playground - limited trial (with no look into Admin actions)

It’s more restricted than that. You can only do stuff in Sandbox. This is the message that is displayed on the home:

This a wiki you can use to try out some of XWiki’s features.

To get started, Register and then log in. Then make all modifications you want in the Sandbox Zone. This home page is protected from edition to avoid the wiki from being defaced.

If you wish to try a fully functional XWiki, including the Administration parts, we recommend signing up for a free trial of XWiki Cloud (Service provided by XWiki SAS, one of the companies sponsoring the development of XWiki).

Note that this wiki is unmoderated and its content is reset automatically every day (including user accounts).

@amilica

• Try XWiki in Playground - limited trial (with no look into Admin actions)
• Try XWiki Cloud - full trial from XWiki SAS with all features (including Admin actions & Pro extensions)
• Download XWiki - full and free acess to the whole project, [license link]
• Account on MyXWiki.org - for non-profit organizations and individuals, no uptime or support warranty, no programming rights

This doesn’t highlight the Standalone distribution which is a trial distribution! (it’s made for this, but it’s not hosted).

[CharpentierLucas]

@tkrieck

Proposal 01: Make the “Try XWiki” button more visible

+1 from me, the drawbacks I could think of are all negligible.

@tkrieck

Proposal 02: Improve the layout of the Hosted page

+1

Sidenote: Here the three options fit on a line. With four options a nice layout would probably be a 2*2 grid.

@tkrieck

Proposal 03: Keep the Playground on the latest version

+0 on this (depending on how easy it would be to automate).

@tkrieck

Proposal 04: Use slides as the main onboarding method

@tkrieck

Replace the current default Tour app aplication with this new Onboarding app, while keeping the Tour app for other purposes.

If we provide an alternative that is good enough for us to make the onboarding with, I believe it would make sense to stop providing the tour extension and application in XS.

@tkrieck

Proposal 06: Make the onboarding app customizable

+1, at least the same level of customizable as the Tour app if we want to replace it.

@tkrieck

Proposal 07: Reduce the Tour App steps

@tkrieck

Proposal:

• Use the Tour app to:
  • Show how to restart onboarding.
  • Highlight the Sandbox for safe experimentation.
  • On first edit, point to the “Done” button so users know how to exit edit mode.

I’m not sure it would even be worth the maintenance and bugs to keep it in XS at this point… note that we can probably do these three things quite well without the tour app

I’m not sure I understood your intention fully but I’m -1 on keeping the tour app if we have another app.
The tour application today is not perfect and relies on an unmaintained dependency. It brings a large chunk of technical debt and being able to remove it from XS (without losing features OFC ) is already a positive from my point of view.

---

Thanks you for looking into these improvements!
Lucas C.