Guided Tutorial Extension Proposal #1

Development
1

Hi everyone!! :waving_hand: :waving_hand:

This proposal is a continuation of what I’ve previously referred to as the “Checklist Extension”. I realized that a “Checklist” extension already exists, so I decided to be a little more specific with the name.

While the previous proposals I’ve made helped me in the ideation process, I believe they also caused unnecessary confusion. Therefore, starting with this proposal I’m hoping to improve in that area.

Going forward, I’m going to make smaller, more focused proposals, and when consensus is reached on the Forum, add that information to a Design page. The Design page is going to be the main source of truth when it comes to the Guided Tutorial extension.

Design page: https://design.xwiki.org/xwiki/bin/view/Proposal/GuidedTutorialExtension

WHAT is the idea behind the Guided Tutorial Extension?

The goal of the Guided Tutorial is to offer practical steps to newcomers. These steps should help new users better understand how to use XWiki properly. It should serve as a tutorial showcasing basic features of XWiki, such as: creating pages, commenting, annotations, uploading attachments & inserting images on pages, inserting macros, mentioning users etc.

A list of tasks would be available for users to go through. The available tasks would be influenced by the extensions installed on the wiki, and the rights of the user. More details about this will be available in a future proposal.

Here’s a little ASCII mockup of how the task checklist section of the Guided Tutorial extension could look like:

+--------------------------------------------------------------------------------+
| My Wiki Page                                                                   |
+--------------------------------------------------------------------------------+
|                                                                                |
| Content                                                                        |
| -------                                                                        |
| Lorem ipsum dolor sit amet, consectetur adipiscing elit.                       |
| Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.             |
|                                                                                |
|                                                                                |
| More Content                                                                   |
| ------------                                                                   |
| Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.            |
|                                                                                |
|                                                                                |
|                                                                                |
|                                             +---------------------------------+|
|                                             | Tasks                           ||
|                                             |---------------------------------||
|                                             | Progress: [###-------] 33%      ||
|                                             |                                 ||
|                                             | [x] Create account on wiki      ||
|                                             |     instance                    ||
|                                             |     Register and sign in to     ||
|                                             |     the wiki system.            ||
|                                             |                                 ||
|                                             | [ ] Create a page               ||
|                                             |     Set up the initial wiki     ||
|                                             |     page structure.             ||
|                                             |                                 ||
|                                             | [ ] Lorem ipsum placeholder     ||
|                                             |     Add placeholder text for    ||
|                                             |     future content.             ||
|                                             |                                 ||
|                                             |---------------------------------||
|                                             | Resources:                      ||
|                                             |  - Documentation                ||
|                                             |  - Community support            ||
|                                             |  - Professional support         ||
|                                             +---------------------------------+|
|                                                                                |
+--------------------------------------------------------------------------------+

WHY is it necessary?

The current first time experience for new users, especially end users (non admins) is brief and, in my opinion, not detailed enough.

A new XWiki end user only gets to see the Tour App, which showcases a couple of UI elements, but it doesn’t prompt for action. This makes it difficult for the user to understand all the capabilities of XWiki.

I tried to estimate how many XWiki instances went offline in 2025. I’m not that familiar with ELK, so please let me know if my methodology is incorrect.

What I did is: I looked at the XWiki Active Installs ELK dashboard, and I slightly changed the end of the filter query (from date.since > 4 to date.since >= 0 then 1, 5, 10). I presume date.since refers to days.

Here are the results:

Day Unique Installs
Day 0 44,589
Day 1 17,046
Day 5 13,904
Day 10 12,305

For Day 0, I presume the number is that big because it includes automated environments, that are not up for a full day. That being said, between instances that are up for at least 1 day, and instances that are up for at least 10 days we can see a drop of 4.7k instances (if I did the math right). That’s thousands of end users that could have used XWiki but currently aren’t, in part due to the lack of an adequate onboarding experience.

HOW should it be improved? (Proposals)

Proposal 1: The Guided Tutorial extension should be developed and bundled by default into XWiki Standard. The development process would follow all rules and quality requirements expected of a bundled component.

Proposal 2: The Guided Tutorial extension should use Cristal technology during its development, as to make it easier to adapt it to Cristal in the future.

Proposal 3: The Tour App should be deprecated after the Guided Tutorial extension is released.

Proposal 4: The Sandbox Space is trying to offer users a way to try out XWiki functionality. Since there’s no explicit prompting for users to do that, I think it currently fails at its goal. Therefore, we need to decide what happens to it:

  • Proposal 4.1: No changes, keep Sandbox Space as is.

  • Proposal 4.2: Entirely remove the Sandbox Space from XWiki Standard.

  • Proposal 4.3: Keep the sandbox space, and make the Guided Tutorial extension interact with it (e.g.: Starting a task would redirect the user to the Sandbox Space, as to not “pollute” the rest of the wiki).

Personally, I’m leaning towards Proposal 4.3. I think the Guided Tutorial and the Sandbox Space could be complementary to each other.

WDYT?
This proposal will collect feedback until 3-Feb-2026, after which I’ll update the Design page with what was agreed on here.

1 Like
Onboarding Status and "Slides" design decisions
Library choice for the new Guided Tour Extension
In-Product Onboarding Revamp Proposal - Checklist Extension
2

~80% retention between day 1 and day 5 and 70% retention between days 1 and day 10 does not seem too bad to me.

How can we ensure the instruction of the guided tutorial stays relevant for the next user? For instance, when a first user has visited the sandbox, followed the instructions, and possibly completely messed with the page content?

1 Like
3

If the guided extension is expected to be part of the standard distribution and a replacement of the tour app, I suggest having a list of all the features existing in the tour app. And then checking if the new extension fulfills them exhaustively (plus more since it’s an improvement).
It could be fine if we don’t support 100% of what the tour app is doing, but we need to be aware of it and to collectively agree on the breakage.

1 Like
4

Some ideas for how to keep the guide relevant for the next user:

  • Use a new page in the Sandbox space instead of the Sandbox page itself. So the user could first get the task to ‘Create a new page’ in the Sandbox space (so we teach page creation + ensure a blank slate to start), then the guided tour could add some content to the page, if we really need it (it could be a simulated user, so we also show the page history/rollback functionality)
  • Provide a link/redirect to the 1.0 version of the page, so the initial text is consistent (would need to check if the 1.0 version is the one expected by the guided tour app). Editing would show another version of the page, though
  • Rollback to the initial version of the Sandbox whenever a user starts the onboarding task (this seems finicky)
1 Like
5

I agree that those are not necessarily bad numbers. But I still think that it would be worth trying to improve the situation if possible.

Great question! This could be the subject of another proposal, if after the current one it is decided to go with option 4.3. Though, I really like this idea from @KebabRonin:

Adding to his idea, I think we could potentially add a “Sandbox Template” so when the user creates a page, we show them how templates work as well.
Again, remains to be seen after it’s decided if we want to go this route or not.

Honestly, great point. I’ll start looking into that and add a table of features to the Design page, so we can better track this. Thank you! :raising_hands:

6

Be aware that the Tour application is currently also used in extensions: e.g. the Forum Extension apparently has a custom Tour using the Tour application (see: application-forum/application-forum-ui/src/main/resources/ForumCode/Forum tour.xml at master · xwiki-contrib/application-forum · GitHub )

I doubt there’s many but it might not be the only ones. Now deprecating it/unbundling it shouldn’t prevent from allowing users to still install or use it when needed.

7

To be honest, I’m wondering if users even see the Tour App: the icon for starting it is very discrete, so it’s very possible very few users are actually used the Tour App today…

It’s interesting to check numbers, but honestly we have no idea why those people didn’t proceed. Maybe they didn’t like the color :slight_smile: I wouldn’t use those as a primary argument but I agree we need better onboarding.

+1 the dev process and tech used are not even to be discussed. But we could discuss whether it should be bundled or not by default. If we’re going to a replacement of Tour then yes it should be bundled.

So on the long run, I agree on a plan where the guided tutorial extension would replace Tour, and so Tour should be moved to the attic and marked as deprecated on extension.xwiki.org. Now this would probably not be done after first release: most likely it will be done when we consider Guided tutorial extension is good enough in quality to replace it.

There’s numerous of questions regarding this… On the principle 4.3 sounds like a good idea. Now let’s say your wiki is entirely protected against edit rights for standard users. How do you handle it? Another solution is to use user profile page: users necessarily have rights on this page, so they are able to edit it and do things with it.

9

I guess because we want that extensions add their own tutorials, we probably will want multiple flows of tutorial, shouldn’t we have some sort of grouping for the steps?
Example:

  • Basic Usage
    • Create Page
    • Add stuff
    • …
  • Another topic
    • Step 1
    • Step 2
    • …
10

Thanks for bringing this to my attention. Do you know how I could check which extensions are using custom tours, so that I can keep track of that on the design page? :folded_hands:

I specifically didn’t get into many details because I wasn’t sure if the community would want to go into this direction, or if it would decide to leave the Sandbox Space unchanged or remove it completely.
The edit-protected wiki usecase would, indeed, be a challenge. I did mention in the proposal that the tasks would be affected by rights as well.

So, at least in theory for now, if you don’t have edit rights, you shouldn’t see any tasks that require them. But that’s probably going to be most if not all the tasks.

On one hand, if the admin doesn’t want a certain group of users to edit pages, maybe it wouldn’t make sense to teach those users how to do that in the first place. On the other hand, it may still be helpful for users to learn about the full XWiki experience, even if they are in a restricted environment.

I think we first need to answer who should have the “authority” on this matter. E.g.:

  • If the admins decides that users shouldn’t edit pages, we shouldn’t teach them how to edit pages
  • We should find a way to show the full XWiki experience (including editing), regardless of the wishes of the admin (weather we do it through profile pages, or other means).

Good point. I think the easiest way to achieve this would be to have a section of “basic tasks”, and then group the other tasks by extension. If we were to group them by topic, it may require some more work to define which task goes in which topic. Plus, I think grouping tasks by extension would be easier for users to understand as well.

11

Well my point is that we cannot really decide on what to do with Sandbox without actually going a bit deeper in those UC if we want to be generic.

And my counter proposition on this, is to consider by default that users would edit their own user profile instead of editing Sandbox. Since, as I mentioned, we’re sure logged-in users always have rights there.

I guess we could consider that first steps of the Guided tutorial would or could be performed when the user is still guest, and one of the step is registering or logging in to continue then the steps as a logged-in users.

12

Ahh, right. I see your point now.

In that case, I propose the following flow:

  • User logs in for the first time
  • The checklist widget appears in the bottom right corner of the screen
  • All the basic tasks are available to them (e.g.: create a page, add a comment etc.)
  • When they click to start one of the tasks, they’re brought to a page under their profile (since it’s guaranteed they’ll have rights here)
  • They do the task

This should happen regardless of the rights on the rest of the wiki.

I wouldn’t necessarily show the tasks widget for users that aren’t logged in. At least not by default. I think we’d run into complications with wikis that don’t accept user sign-ups. Though at the same time, on bigger wikis such as XWiki.org, it could encourage more users to sign up, and maybe even contribute?

About the registration task though, I do think that it should be present to logged-in users, but it should be already checked off. This would encourage the users to continue with the other tasks, since it would feel like the process has already started. Otherwise, it would feel more like a choice if they want to do the tasks now, or later, which may lead to them ignoring the tasks completely.

Source: User Onboarding | A frequently-updated compendium of web app first-run experiences
Quote:

Small execution nitpick: It feels like a bummer when Zendesk starts you off at 0% inside the app after you’ve answered five onboarding questions getting there

13

I just thought about this, so I’d like to ask for some feedback. But do we want the tasks to be linear, in the sense that you have to do them in order, or should we allow users to start whichever task they want at any time?

Initially I was thinking the latter, because I (maybe wrongly) presumed that the tasks would be done inside the Sandbox, where pages are already created. But if we want users to do the tasks in their profile, since we can ensure they have rights there, then we’d first need them to create a page before they can do other tasks such as adding comments.

Could a page be created automatically if a user decides to start the tasks in a different order? Would it even be worth it to bother with this much complexity when we can just enforce a order to the tasks?

WDYT?

14

User profiles are terminal pages, there can’t be any pages below them. See also Personal Pages feature

15

Note that right now the Tour app dialog appears when you reach the wiki, even before you logged in:

image
image1925×932 103 KB

I think we probably shouldn’t lose that, and help users getting registered / logged in in the wiki. For me it’s a whole part of the onboarding.

I’d be interested to get @tkrieck feedback on that, but I’d say we might need to support both in Guideline Tutorial Extension. I’m sure that some tasks will have prerequisite, so we need for sure to support order in tasks. Now I do believe that maybe some tasks could be done in parallel, and maybe we would want to present them that way, but I’m a bit less sure on that part.

16

I think a good way would be to search all xwiki repos for the Tour Class. It seems that over all xwiki, contrib and xwikisas repos, only Forum, XCS, and the platform have some tours defined.

https://github.com/search?q=org%3Axwikisas+OR+org%3Axwiki-contrib+OR+org%3Axwiki+%3Cname%3ETourCode.TourClass%3C%2Fname%3E&type=code

1 Like
17

Ahh, thank you for pointing this out. So if we want users to do tasks somewhere in their profile (since we are sure they have rights there), we should also try to make progress on the Personal Pages proposal? Did you have something else in mind @surli?

Ok, in that case I think it would be ok to have a single task for guest users, that being something along the lines of “Create an account”. But I still think the availability of tasks for guest users should be something configurable by the admin.

In that case, sure, let’s support both. As long as it’s not too much of a development burden, I’m all for it.

Thank you!! :heart_hands: :heart_hands:
I’ll add the repos to the design page soon, so we can keep track of them.

18

Was actually thinking about directly modifying their personal page, since you can create content in there, but it won’t fit a UC where you propose users to create pages indeed.

We need to improve Personal Pages proposal but that shouldn’t block work on this. We could provide a config for this in the app, for admins to select the space where users could perform changes, and later on to deprecate it to propose using Personal pages whenever it’s properly available.

+1 for something configurable. It could also come from reading the rights: i.e. if guest has comment rights it would make sense to have a task for comments maybe.

My point is more that the design should maybe support it, even if we don’t implement that support right away. But it’s a maybe, I’m still not 100% sure we need that.

1 Like
19

Sounds good to me. We could make the Sandbox Space the default, giving admins the option of changing it if they wish, and when personal pages are available, we could move to that.

I like this idea. +1 on having all possible tasks, based on rights, available to guests (if the admin kept the checklist widget for logged-out users).

20

Great, thx for working on this Gabriel! :slight_smile:

+1 for a new name (but not because there’s already an extensions - which IMO we should remove as there’s no doc for it) but because a checklist extension can be a lot of things and thus the name is not precise enough.

Now re the new name, we could also name it “Guided Tour” which IMO is a bit more precise than “Guided Tutorial” (which could still be about a lot of things).

Another option is to call it “Guided Tasks Application”, “Task List Application”, or some other name with “Task” in the name since it seems to be about tasks (and NOT about “tutorials” - calling a task a tutorial seems a bit stretching the concept of tutorial IMO).

It seems to me that it shouldn’t be restricted to basic features and that we could have some extensions offering non-basic features and still using this extension to let the users learn how to use its features, no?

I think we need to allow extensions to contribute tasks (rather than the main app knowing about other extensions).

I’m not sure how you infer that it’s partly due to the lack of an adequate onboarding experience from those figures (assuming they’re correct, I didn’t check). I’m not saying it’s false but it could be for lots of other reasons, the first one being simply that it doesn’t match the user’s needs, the users don’t like the UI or L&F, etc.

It would have been more interesting to have usage information in the XWiki (something we’re currently lacking, see https://design.xwiki.org/xwiki/bin/view/Proposal/UsageStatistics).

+1

+1

+1 (and move the Tour app again as a contrib app so that it can still be installed).

I’m not sure how you infer that “Since there’s no explicit prompting for users to do that, I think it currently fails at its goal” without usage information. Again I’m not saying it’s false, just that we don’t know.

That said, I agree that this app and the Sandbox app are fulfilling the same role (this app being a more elaborate version of the Sandbox), and thus that we don’t need both.

I’m more in favor of 4.2 since, as part of the tasks, we should probably ask the user to create a new page in some space, and add some content, thus recreating something similar to the content of the Sandbox page. Then use this page for other dependent tasks such as adding a comment, mentioning someone, etc.

I also agree that it’s pretty good if the figures are true.

They cannot miss it since it opens a dialog in the middle of the screen the first time they log in :slight_smile:

+1

Thx

1 Like
21

“Guided Tour (Application?)”, or “Guided Tasks Application” sound good to me. I don’t have strong feelings towards a particular name, I just wanted to not clash with the already existing “Checklist” extension and I used the first thing that came to mind :sweat_smile:. From my POV, it can, and probably should be changed by the time it gets released.

Yes, it shouldn’t be restricted to basic features. To clarify, when I say “showing basic features” I’m referring to the bare minimum guided tour that should be available to users in case there are no other extensions available to users, or if the admin chooses to disable those particular tasks.

But the extension should have the ability to show more complex tours / tasks as well.

Agreed. Extensions should be able to create their own tasks and tours. Apologies for not making that clear.

Valid criticism. I said that because when I first experienced XWiki, I thought the Sandbox Space was there to showcase what can be done with XWiki Syntax. I later learned that the initial goal of the Sandbox Space was to offer users a place where they could try out XWiki functionalities (e.g. create pages, edit pages etc.). For me in particular, it “failed at its goal” because it made me think the space had a different goal (showcasing syntax). But it indeed isn’t fair to generalize my experience.