Guided Tutorial Extension Proposal #1

[mleduc]

We had a meeting to discuss the technical choices to start the implementation of the guided tutorial extension (or any other name we end up with).
And while discussing, we realized that we don’t have enough information to make a choice.

See below a list of questions we were unable to answer:

• Do we still want to be able to focus on specific elements during a step?
• In Proposals for improving the Onboarding Experience - #18 by gabrielc and in the ASCII mockup we can see checkboxes. When and how do they change state?
• How do we know if an achievement condition is met?
• Since the tour is “guided”, what happens when the achievement condition is met? Taking an imaginary use case where the user is asked to type “hello world” in a field, then asked to press a submit button once “hello world” is typed
  • What happens right after “hello world” is typed?
  • Is the user moved to the submit button?
  • Is the move done with a delay or a transition?
  • Or does a checkbox become checked and the next step button enabled?

Overall, I think we need example scenarios to better understand the user flow of the guided tutorials.

Furthermore, given the extensible nature of the extension, what happens when two tutorials can be activated for a given user at the same time?

• Are they merged?
• Is one of the tutorials put on hold until the first one is done, before being proposed to the user?

I’m also wondering if we want to have a precondition for a tutorial to start, for instance:

• An introduction tutorial starting on the first login of a user.
• An admin tour the first time a user accesses the administration
• An edit tour the first time a user clicks on the editor button
• A “more actions” tour the first time the user clicks on more actions (or maybe just after a predefined duration, and only once the introduction tutorial is completed)

What happens if a user discards a tutorial? Are all the future tutorials discarded as well?

cc @tkrieck since the answers might impact your UX design.

[surli]

@mleduc

Do we still want to be able to focus on specific elements during a step?

For a concrete example, during the meeting I took the example of “Task for creating a page” where the user should be:

1. Invited to click on “Create” button
2. Invited to type a page name
3. Invited to select a template
4. Invited to click on create
5. Invited to modify the template content
6. Save

The way I was seeing it, at each step there would a highlight on the UI areas with a bit of explanations, before the user actually performs the action. So for step 1, we highlight the “Create” button, we put a quick message to invite to click on it, etc. Step 2 is a bit more complex since it involves interaction with the form to provide input in a text field, but otherwise it’s same idea.

So globally I’m seeing something very guided: tasks are completed through a list of small steps with highlights on the UI. Each task could almost be seen as a tiny tour on its own.

A very different way of seeing it is to consider that we provide a list of tasks to user, and we let them complete the tasks without providing guidance: we just inform them when they completed the task. If we go there, then we don’t need at all the Tour application concepts, the guidance is much more limited.

So I think we should ensure we’re all on the same page between those 2 options.

[gabrielc]

@mleduc

Do we still want to be able to focus on specific elements during a step?

Yes. The first option explained by Simon is also what I had in mind:

@surli

1. Invited to click on “Create” button
2. Invited to type a page name
3. Invited to select a template
4. Invited to click on create
5. Invited to modify the template content
6. Save

The way I was seeing it, at each step there would a highlight on the UI areas with a bit of explanations, before the user actually performs the action. So for step 1, we highlight the “Create” button, we put a quick message to invite to click on it, etc. Step 2 is a bit more complex since it involves interaction with the form to provide input in a text field, but otherwise it’s same idea.

@surli

So I think we should ensure we’re all on the same page between those 2 options.

I’m +1 for the first option, as I believe it would provide more value to first time users.

@mleduc

In Proposals for improving the Onboarding Experience - #18 by gabrielc and in the ASCII mockup we can see checkboxes. When and how do they change state?

Checkbox state should change upon task completion. At the end of a task, an event should be fired, or a function related to the checkbox widget should be called (unsure about the technical implementation, maybe there are better ways of achieving this), that would update the state of the checkbox.

@mleduc

How do we know if an achievement condition is met?

I’m not sure that I understand. Could you please offer some more details, or an example?

@mleduc

Since the tour is “guided”, what happens when the achievement condition is met? Taking an imaginary use case where the user is asked to type “hello world” in a field, then asked to press a submit button once “hello world” is typed

• What happens right after “hello world” is typed?
• Is the user moved to the submit button?
• Is the move done with a delay or a transition?
• Or does a checkbox become checked and the next step button enabled?

For each step of a task the focus of the page should be brought to a certain element. A popup should be visible, guiding the user through text about the action they’re expected to take.

If we already know the value expected to be typed in a text field, in this case “hello world”, after the user does that, the focus should be moved to the submit button, using an animation. The animation should be disabled if the browser has the “Reduced Motion” accessibility feature enabled.

That being said, in some cases, we might not know beforehand what the user will type in a field (e.g.: a page creation task should let the user give the page whatever name they want). In those cases, a “Next” button should be available in the popup, to let the user choose when to go to the next step.

The checkbox in the checkbox widget should only change state when the task is fully completed.

@mleduc

Overall, I think we need example scenarios to better understand the user flow of the guided tutorials.

Good point, I’ll work on a couple of detailed examples and post them on the forum next week.

@mleduc

Furthermore, given the extensible nature of the extension, what happens when two tutorials can be activated for a given user at the same time?

A user should not be able to start 2 or more tutorials at the same time. I think that would cause confusion to the user and unnecessary development complexity.

If the user somehow triggers a new tutorial during an already ongoing tutorial, the new tutorial should be added as a task in the checklist widget, and the user should be able to trigger it manually after they’re done with the current tutorial.

@mleduc

I’m also wondering if we want to have a precondition for a tutorial to start, for instance:

• An introduction tutorial starting on the first login of a user.
• An admin tour the first time a user accesses the administration
• An edit tour the first time a user clicks on the editor button
• A “more actions” tour the first time the user clicks on more actions (or maybe just after a predefined duration, and only once the introduction tutorial is completed)

I really like the idea of showing tutorials to users when they first encounter a feature. That being said, this was not part of the proposal. I think for now it would be best to focus on clearly defining how tasks work. In my opinion, this would be a nice feature to have, but maybe in a V2 of the extension.

@mleduc

What happens if a user discards a tutorial? Are all the future tutorials discarded as well?

If a user discards a currently ongoing task, all progress on that task should be lost. The user should be able to restart the task from the beginning at a later time.

Admins should have a config option available to let users skip all task if they want to.

If a user wants to skip all the tasks, let’s say they’re already familiar with XWiki, they should be able to do that only if the admin allows for it.

Users should also be able to reset their tasks, in case they forgot how to do certain things, or in case they initially skipped the tasks but now want to do them. I am currently unsure where this task reset feature should be found. Potentially in a submenu of the task widget (?).

[surli]

@gabrielc

@mleduc

How do we know if an achievement condition is met?

I’m not sure that I understand. Could you please offer some more details, or an example?

I think the question is: do we consider that the task is finished when the user achieve last step of the task, or do you want to have other condition too? e.g. for the “Creation of page tutorial”, if we can validate the user click on “save” at step 6, is it enough to mark the task complete, or do we want to also check that a page has been created by the user? In this scenario it’s redundant, but maybe in some scenario that would make sense to check a condition? Or is it overengineering it?

@gabrielc

If we already know the value expected to be typed in a text field, in this case “hello world”, after the user does that, the focus should be moved to the submit button, using an animation. The animation should be disabled if the browser has the “Reduced Motion” accessibility feature enabled.

That being said, in some cases, we might not know beforehand what the user will type in a field (e.g.: a page creation task should let the user give the page whatever name they want). In those cases, a “Next” button should be available in the popup, to let the user choose when to go to the next step.

So my understanding of that is that:

1. each step is related to a UI element (can we have a step not highlighting any element?)
2. a step might wait a user input on the element for going to next step
3. the user input might need a specific validation (e.g. the user typed “hello world” and not “foobar”)
4. in case there’s no validation and no input expected, we should display button to go to next step

[mleduc]

@gabrielc

@mleduc

How do we know if an achievement condition is met?

I’m not sure that I understand. Could you please offer some more details, or an example?

Since the tutorials are guided, we need to have a mechanism to detect when a given step is achieved.
One basic case, such as the example where the user is asked to type a specific text, detecting achievement is easy. It can be checked directly client side.
But, for some other achievement, the check could be more complex and involve interactions with the server.
I don’t have specific cases in mind but I thinks it is interesting to imagine realistic scenairios, to check what would be the achievement solution, and to validate that they can be supported by the extension.
Based on that we’ll know if a expressions are enough or if we need to allow more advanced scripting to define steps achievement condition.

@gabrielc

I really like the idea of showing tutorials to users when they first encounter a feature. That being said, this was not part of the proposal. I think for now it would be best to focus on clearly defining how tasks work. In my opinion, this would be a nice feature to have, but maybe in a V2 of the extension.

I don’t think we can avoid this for long since the legacy tour extension already had a close concept with the target page and target class properties of a tour. Allowing to only start a tour when the user visits a given page or when a page contains a given class (see https://extensions.xwiki.org/xwiki/bin/view/Extension/Tour%20Application#HHowtocreateanewTour).
If we want the guided tutorial extension to be a replacement for the tour, we’ll have to support something equivalent.

@gabrielc

If a user wants to skip all the tasks, let’s say they’re already familiar with XWiki, they should be able to do that only if the admin allows for it.

-1 to let the admin “force” tutorial to user like this, or at least not as the default option.

@gabrielc

If a user wants to skip all the tasks, let’s say they’re already familiar with XWiki, they should be able to do that only if the admin allows for it.

Ok, we’ll need a specification of the different screens needed for this use case, like where the user can see the steps they skipped earlier and so on.

[gabrielc]

@gabrielc

@mleduc

Overall, I think we need example scenarios to better understand the user flow of the guided tutorials.

Good point, I’ll work on a couple of detailed examples and post them on the forum next week.

Here is my first proposal for the default tasks:

1. Create a page

1.1. Click “Create” button
1.2. Enter a title
1.3. Select a template [maybe we create a “tutorial template” that we force users to pick, so the page isn’t completely blank]
1.4. Click “Create”
1.5. Modify page content (optional)
1.6. Click “Done”

2. Leave a comment

2.1. Focus the “Comments (0)” section
2.2. Click the “Comment” button
2.3. Add your comment [could be whatever, we shouldn’t check contents]
2.4. Click “Add comment”

3. Add an annotation

3.1. Select some text and press “CTRL + M” [ or Command + M on Mac?]
3.2. Add your annotation text
3.3. Click on “Add annotation”
[bring focus to Comments section]
3.4. Click on the quoted text above your annotation

4. Upload an attachment

4.1. Focus the “Attachments (0)” section
4.2. Click on “Browse…” under the “Attach files to this page” section
4.3. Select a file from your system

5. Insert a macro on a page

[Check if users is already in edit mode. If user is already in edit mode, skip to 5.2.]
5.1. Click “Edit”
5.2. Type “/info”
5.3. Select the “Info Box” macro
5.4. Modify Info Box content (optional)
5.5. Click “Done”

6. Mention a user

[Check if users is already in edit mode. If user is already in edit mode, skip to 6.2.]
6.1. Click “Edit”
6.2. Type “@”
6.3. Select a user
6.4. Click “Done”

7. Insert an image

[Check if users is already in edit mode. If user is already in edit mode, skip to 7.2.]
[The template used for tutorial pages should contain at least one image, in case the user uploads another kind of document]
7.1. Click “Edit”
7.2. Type “/image”
7.3. Select the “Image” macro from the “Content” section
7.4. Select or upload an image
7.5. Click “Done”

8. View differences between 2 versions of the page

8.1. Focus the “History” section
8.2. Click “Compare selected versions”

---

I think we should encourage users to save after every page content related task, and keep the History related task towards the end, so that when the user gets to it, there are actual changes that they can see.

[gabrielc]

@surli

I think the question is: do we consider that the task is finished when the user achieve last step of the task, or do you want to have other condition too? e.g. for the “Creation of page tutorial”, if we can validate the user click on “save” at step 6, is it enough to mark the task complete, or do we want to also check that a page has been created by the user? In this scenario it’s redundant, but maybe in some scenario that would make sense to check a condition? Or is it overengineering it?

I’d go with “task is finished when the user archives the last step of the task”. Unless something really bad happens along the way, I think it would be enough. And if something bad does happen, the user could restart / reset the task. (When I say “bad stuff” I’m mainly thinking about network conditions).

@surli

can we have a step not highlighting any element?

I’m not sure how task steps such as “type /info on a page in edit mode, and select the Info Box macro” could be highlighted. In cases like this, if it would be too hard to highlight a certain line in edit view, we could potentially have steps without element highlights. Or maybe just focus the editor in this case?

@surli

So my understanding of that is that:

1. each step is related to a UI element (can we have a step not highlighting any element?)
2. a step might wait a user input on the element for going to next step
3. the user input might need a specific validation (e.g. the user typed “hello world” and not “foobar”)
4. in case there’s no validation and no input expected, we should display button to go to next step

Yep. That sounds good.

@mleduc

But, for some other achievement, the check could be more complex and involve interactions with the server.
I don’t have specific cases in mind but I thinks it is interesting to imagine realistic scenairios, to check what would be the achievement solution, and to validate that they can be supported by the extension.

Could you please check the proposed tasks and let me know if any of them would require server validation or something more complex? If only 1-2 tasks are more painful to implement, they could be switched to something else. Over all, since it is easier, I think validation of tasks could be done client-side.

@mleduc

I don’t think we can avoid this for long since the legacy tour extension already had a close concept with the target page and target class properties of a tour. Allowing to only start a tour when the user visits a given page or when a page contains a given class (see https://extensions.xwiki.org/xwiki/bin/view/Extension/Tour%20Application#HHowtocreateanewTour).

Ah, fair. In that case, it should be done.
I don’t think it would be used in the default tours at first, but if the feature is already there, it would be easier to create more tours later, for certain pages.

@mleduc

-1 to let the admin “force” tutorial to user like this, or at least not as the default option.

My thinking was that in some contexts, the admin may want or need to “force” users to do some tasks. It may not only be the default tasks, but some custom tasks they created, that need to be done for compliance reasons for example (e.g.: make sure a user reads a procedure, then signs their name in an AWM).

That being said, I’m fine with letting users skip tasks by default. But I do think the option should be there in case it is needed in certain use cases.

@mleduc

Ok, we’ll need a specification of the different screens needed for this use case, like where the user can see the steps they skipped earlier and so on.

Yeah, I’ll have to work with Thiago on this. I’ll let you know when we have something ready.

[CharpentierLucas]

That’s some interesting use cases.
Those look quite different from what we can do today with the tour-app.
Note that recently I updated the tour to make its content less interactive: Proposal: prevent interacting with highlighted content during the TOUR

If we want to deprecate the tour-app, we’d need to make sure every step has a isInteractive field, so that we can keep the “show item>click next” use case supported.

---

2.3. Add your comment [could be whatever, we shouldn’t check contents]

5.2. Type “/info”

Note that we’ll need to check the editor content for 5.

---

I think that for any step, it would be important to add a “skip step” button to make sure the user doesn’t get stuck because there’s a bug in the step validator (could be caused in some places by heavy customization).

---

Maybe the guided tutorial should be bundled with its own template pages that are instanced on every tutorial and deleted after the end, so that actions on it wouldn’t change the state of the wiki. E.g. if I have 10000 users and everyone adds some text, an attachment and an annotation on the Sandbox page, things could get very messy really quick. Even if it’s just a Sandbox, my 9800th user would probably be disappointed with how the page looks/loads. I think the edits made during the guided tutorial should be only throwaway information and that it’s okay to delete them after the end of the tutorial.

[gabrielc]

To summarize, this is where we’re at now:

Agreed

• The extension will be part of XWiki Standard
• The extension will have most, if not all the features currently available in the Tour App
• After the extension is released, and after it is agreed that it reached a certain threshold of quality, it will replace the Tour App, which will then be marked as deprecated and moved to contrib
• Some tasks should be visible to Guest users as well, based on rights. Admins could disallow tasks to Guest users
• Every step should offer an isInteractive field, for accessibility reasons

What should the extension be able to do

• Offer a widget with tasks
• Guide users to complete tasks by focusing UI elements
• Let other extensions create custom tours
• Let tours be triggered automatically when the user visits a certain page
• If a task is already started, another task shouldn’t start at the same time
• Checkbox status should change upon task completion. Tasks should be marked as completed when the last step is finished

Still needs to be discussed

• Tasks should be grouped. Besides the main tutorial tasks, do we group them by task topic, or by extension providing the task e.g.:
  • Main Tasks + Topic 1, Topic 2…
  • Main Tasks + Extension 1, Extension 2… (+1 from me)
• Should we:
  • Only support linear tasks (done one after the other)
  • Only support ad-hoc tasks (order doesn’t matter)
  • Support both linear & ad-hoc tasks (+1 from me)
• Users should be able to skip tasks by default, but admins should have the option to enforce certain tasks
• Every step should be skippable, in case the step validator stops working (e.g.: due to heavy customizations on the wiki)
• Where should tasks be done? I like the proposal made by Lucas:

@CharpentierLucas

Maybe the guided tutorial should be bundled with its own template pages that are instanced on every tutorial and deleted after the end, so that actions on it wouldn’t change the state of the wiki. E.g. if I have 10000 users and everyone adds some text, an attachment and an annotation on the Sandbox page, things could get very messy really quick. Even if it’s just a Sandbox, my 9800th user would probably be disappointed with how the page looks/loads. I think the edits made during the guided tutorial should be only throwaway information and that it’s okay to delete them after the end of the tutorial.

To do

• Create specification of different screens needed for configuration, skipped tasks etc.

[surli]

@gabrielc

@surli

can we have a step not highlighting any element?

I’m not sure how task steps such as “type /info on a page in edit mode, and select the Info Box macro” could be highlighted. In cases like this, if it would be too hard to highlight a certain line in edit view, we could potentially have steps without element highlights. Or maybe just focus the editor in this case?

Interesting UC, I see two non exclusive options for such case:

1. we put a small gif or video illustrating the action to perform (cheapest solution and probably very effective)
2. we provide an automation mechanism allowing to actually perform the action: i.e. the user clicks on a button and the users automatically sees the editor being focused and `/info` being typed

@gabrielc

My thinking was that in some contexts, the admin may want or need to “force” users to do some tasks. It may not only be the default tasks, but some custom tasks they created, that need to be done for compliance reasons for example (e.g.: make sure a user reads a procedure, then signs their name in an AWM).

Sounds like a very advanced UC to me, I certainly wouldn’t introduced that in first iterations.

@CharpentierLucas

I think that for any step, it would be important to add a “skip step” button to make sure the user doesn’t get stuck because there’s a bug in the step validator (could be caused in some places by heavy customization).

---

So one way for that is that the “next step” button would never be disabled: the “validator” would just highlight that the step has been done with an icon/a color, but even if the step is not validated user would be allowed to continue (maybe with a confirmation).

Note that this behaviour could be a configuration probably.

@CharpentierLucas

Maybe the guided tutorial should be bundled with its own template pages that are instanced on every tutorial and deleted after the end, so that actions on it wouldn’t change the state of the wiki. E.g. if I have 10000 users and everyone adds some text, an attachment and an annotation on the Sandbox page, things could get very messy really quick. Even if it’s just a Sandbox, my 9800th user would probably be disappointed with how the page looks/loads. I think the edits made during the guided tutorial should be only throwaway information and that it’s okay to delete them after the end of the tutorial.

Yes I agree for the tasks to be performed we need to be careful about the backend mechanism we exactly want to provide to not mess up the wiki, have no scalability issue, deal properly with rights and notifications etc.

[gabrielc]

@surli

Interesting UC, I see two non exclusive options for such case:

1. we put a small gif or video illustrating the action to perform (cheapest solution and probably very effective)
2. we provide an automation mechanism allowing to actually perform the action: i.e. the user clicks on a button and the users automatically sees the editor being focused and /info being typed

+1 for the GIF. I think it would be quite effective, but we need to make sure to update it if something changes

@surli

Sounds like a very advanced UC to me, I certainly wouldn’t introduced that in first iterations.

Fair

[tkrieck]

@gabrielc

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

Hi everybody, together with @gabrielc we created some mockups to better illustrate the concept of the Guided Tutorial. Below you can check a basic usage of the tour app. Other flows will be posted in the design page illustrating other aspects of the UX, like collapsing Tours, resetting tasks, marking as completed and so on.

We got a round of internal feedback in a UX Session today (Feb 17th) and these mockups still need to have minor adjustments based on that, but the basic usage remains the same.

Here we have the “Getting Started Tour” with the tasks proposed in this reply Guided Tutorial Extension Proposal #1 - #27 by gabrielc

The tasks themselves can change over the course of development, of course. Here you can have a good notion of concepts like:

• The progress bar
• Active Task
• Complete Tasks
• Grouping of Tasks
• Useful links section

Note: The dots above the title on the step description dialog need to be updated based on how many steps there are and the current step. Someone pointed that out to me during the session, and I still have to update it.

Basic flow

[gabrielc]

@tkrieck

Hi everybody, together with @gabrielc we created some mockups to better illustrate the concept of the Guided Tutorial. Below you can check a basic usage of the tour app. Other flows will be posted in the design page illustrating other aspects of the UX, like collapsing Tours, resetting tasks, marking as completed and so on.

Thank you for the mockups, Thiago!
They help a lot with visualizing how the feature should end up looking.

---

Some definitions:
Tour: A grouping of tasks.
Task: A grouping of steps.
Step: Individual actions a user has to take to accomplish something in the UI.

@gabrielc

Still needs to be discussed

As an update, I think we now also have consensus on the following:

• Tours will grouped by “Getting Started” (main tour) + Extension name for any additional tours (if available)
• The extension should support task dependencies, meaning that some tasks would be available only after completing other tasks. If no task dependencies are defined, tasks can be started in any order. (e.g.: You need to first finish the “Create a page” task before the “Add a comment” and “Insert an image on a page” tasks become available. But once they become available, you can start them in any order)
• Users will be able to skip tasks. Either by starting the task and clicking on “Skip this task”, or by hovering over the uncompleted task in the checklist widget and clicking on the icon that will appear to the right of the task name.

---

We still need to talk about where users will do the tasks. Based on previous discussions, I propose the following:

• The extension should ship with its own space + template.
• The space would be excluded from search, as to not pollute searches.
• When a user starts the tour with the “Create page” task, we automatically redirect the user to this space and make them create the page there (by clicking the “Create” button). The page created should use the provided template
• If the user skips the “Create page” task, we automatically create a page for them based on their username (e.g.: “Tutorial page for [USERNAME]”)
• All the other tasks that depend on a page being created / existing, upon start would redirect the user to this particular page
• When all the tasks are finished (or skipped) we show a modal congratulating the user
  • The modal would contain a generic button (e.g.: “Let me explore on my own” or something)
  • The modal would also contain a checkbox with which the users could delete their tutorial page (e.g.: “Check this if you want to delete your tutorial page”)
  • The default state of the checkbox should be configurable by the Admin. Without admin intervention, the state should be unchecked, to not lead to accidental data loss (even though I can’t really imagine what kind of important data a user may store in these pages)
  • Admins should also have the option to batch delete pages in this space that are older than X days, in case they end up causing performance issues.

What are your thoughts on this?
cc: @surli @mleduc @KebabRonin @ChiuchiuSorin @CharpentierLucas

---

We also need to figure out how to store Tour progress. Here I propose the following:

• We temporarily store Step data into cookies / local storage for tasks that require going through different pages. When the task is completed, we can remove this data.
• For Tasks and Tours we store only if they’re completed or not (true / false, 1 / 0), so we can show this in the checklist widget. Where this data would be stored best, I’m currently not sure. Suggestions are welcome

LMK what you think!
Also, if there are any other technical aspects that still need to be discussed, please let me know!

[gabrielc]

After discussing with @KebabRonin and @ChiuchiuSorin, we’ve realized we also need to clarify the following:

Behavior for missing target element

We can make DriverJS wait for an element to appear on a page, then the library would bring focus to that element. What should happen if, for whatever reason, the element doesn’t appear on the page?
Proposal: We wait for the DOMContentLoaded event, after that we start a 5-second timer. If the element doesn’t appear on the page after the timer, we discard the Task and show an error to the user, so they know something went wrong with the tour.

Define backdrop click behavior

In Thiago’s mockups, the backdrop is transparent, only the popup is visible. This means that users may click on elements other than the highlighted element. How should we handle this?
Proposal: If a user clicks on the backdrop / items other than the currently highlighted element, we discard the current task.
Before we discard the current task, we show the user a modal, notifying them that they’ll lose their progress if they continue with the action they’re trying to perform. This way we prevent users from losing progress because of accidental clicks outside the highlighted area.

Backwards compatibility

Is it a requirement that we use all the attributes currently present in the original Tour App?
Proposal: No. We should maintain feature parity with the Tour App, but the goal of the Guided Tour is not to be a drop-in replacement for the Tour App.
To keep in mind: Currently, the Forum App is the only contrib extension making use of a custom tour through the current Tour App.

What does it mean for the Guided Tour to be bundled in XWiki Standard?

We already agreed that the Guided Tour App should be bundled in XWiki Standard.
We have also agreed that we won’t deprecate the current Tour App until the Guided Tour App is of sufficient quality.
In this context, what does it mean for the Guided Tour App to be bundled in XWiki Standard?
Will it be installed but disabled by default? Will it not be installed but available for install by admins? Some clarifications would be necessary here.

Conditional tasks functionality

What happens when a child task is done during a parent task (e.g.: during the “Create a page” task, a user inserts an image on the page)?
Proposal: We only validate the currently running task. For example, if the user inserts an image on the page during the “Create a page task”, at the end of the task we only validate the “Create a page task”. The user could then start the “Insert an image on a page” task, and insert another image, or they could decide to skip the task entirely. We leave it up to the user.

What is the flow of conditional tasks?
Proposal: After the user finishes a task, we ask them if they’d like to start the next one. The order in which the tasks are displayed in the widget, will be the default order of the tasks.
If a user doesn’t want to follow our task order, of if they, for whatever reason, have to stop doing the initial tasks, then they are able to start tasks in whichever order they want, as long as those tasks don’t depend on other tasks, or if the tasks they depend on have already been completed.
For example: If the user already finished the “Create a page task”, they could choose to start the “Add a comment” or “Insert an image on a page” tasks, in whichever order they want. If the user didn’t do the “Create a page” task, the child tasks will be locked until they finish the parent task.

Should child tasks be hidden until the parent task is completed?
Proposal: No. Child tasks should be visible, but appear as disabled. We could show disabled tasks by making the text grayer, and setting the CSS cursor option to not-allowed (cursor: not-allowed;).

Mockups potentially necessary. CC: @tkrieck

Other proposals

• The widget containing tasks should be movable by the user on all axis (left-right, up-down). This ensures that it won’t cover up important content.

@gabrielc

• The extension should ship with its own space + template.
• The space would be excluded from search, as to not pollute searches.

Proposal: We achieve this by only giving view rights to the page, to the user that created it.

@gabrielc

For Tasks and Tours we store only if they’re completed or not (true / false, 1 / 0), so we can show this in the checklist widget. Where this data would be stored best, I’m currently not sure. Suggestions are welcome

Can / should this data be stored in the user page?

Long ahh post. Anyway, WDYT!

[surli]

@gabrielc

Behavior for missing target element

We can make DriverJS wait for an element to appear on a page, then the library would bring focus to that element. What should happen if, for whatever reason, the element doesn’t appear on the page?
Proposal: We wait for the DOMContentLoaded event, after that we start a 5-second timer. If the element doesn’t appear on the page after the timer, we discard the Task and show an error to the user, so they know something went wrong with the tour.

In such scenario if the element doesn’t appear it would be a bug, I’m not sure to see why you’d discard the task though: maybe the bug happens in some specific condition and it would be ok after e.g. a restart of the wiki? Or maybe you don’t have same meaning than me for “discard the task”? If it’s only temporary it’s ok.

Also the 5sec timer feels like quite a lot, I’m not sure we’d need this but I’m not against either.

@gabrielc

Define backdrop click behavior

In Thiago’s mockups, the backdrop is transparent, only the popup is visible. This means that users may click on elements other than the highlighted element. How should we handle this?
Proposal: If a user clicks on the backdrop / items other than the currently highlighted element, we discard the current task.
Before we discard the current task, we show the user a modal, notifying them that they’ll lose their progress if they continue with the action they’re trying to perform. This way we prevent users from losing progress because of accidental clicks outside the highlighted area.

I’m not sure: I would prevent users from leaving the current page, but I wouldn’t forbid any click any where else. For example, if the action is about clicking an entry in the “more actions” menu, I wouldn’t necessarily forbid the user to click elsewhere, as long as they open back the more action menu to click on the highlighted item. But that’s debatable.

@gabrielc

Backwards compatibility

Is it a requirement that we use all the attributes currently present in the original Tour App?
Proposal: No. We should maintain feature parity with the Tour App, but the goal of the Guided Tour is not to be a drop-in replacement for the Tour App.
To keep in mind: Currently, the Forum App is the only contrib extension making use of a custom tour through the current Tour App.

We should have ways to easily migrate existing tour, as much as possible, but I agree we don’t need a strict feature parity.

@gabrielc

What does it mean for the Guided Tour to be bundled in XWiki Standard?

We already agreed that the Guided Tour App should be bundled in XWiki Standard.
We have also agreed that we won’t deprecate the current Tour App until the Guided Tour App is of sufficient quality.
In this context, what does it mean for the Guided Tour App to be bundled in XWiki Standard?
Will it be installed but disabled by default? Will it not be installed but available for install by admins? Some clarifications would be necessary here.

So the standard way of dealing with this kind of thing is the following timeline:

1. the code is provided in XWiki Standard repositories (xwiki-platform here), but the extension is not bundled. The extension can be installed as any other extension, but we inform in the extension page that it’s still exploratory
2. When the extension is ready, we bundle it and we move Tour to contrib, and we stop bundling that one

So for now the new app won’t be bundled.

@gabrielc

Conditional tasks functionality

What happens when a child task is done during a parent task (e.g.: during the “Create a page” task, a user inserts an image on the page)?
Proposal: We only validate the currently running task. For example, if the user inserts an image on the page during the “Create a page task”, at the end of the task we only validate the “Create a page task”. The user could then start the “Insert an image on a page” task, and insert another image, or they could decide to skip the task entirely. We leave it up to the user.

+1

@gabrielc

What is the flow of conditional tasks?
Proposal: After the user finishes a task, we ask them if they’d like to start the next one. The order in which the tasks are displayed in the widget, will be the default order of the tasks.
If a user doesn’t want to follow our task order, of if they, for whatever reason, have to stop doing the initial tasks, then they are able to start tasks in whichever order they want, as long as those tasks don’t depend on other tasks, or if the tasks they depend on have already been completed.
For example: If the user already finished the “Create a page task”, they could choose to start the “Add a comment” or “Insert an image on a page” tasks, in whichever order they want. If the user didn’t do the “Create a page” task, the child tasks will be locked until they finish the parent task.

+1

@gabrielc

Should child tasks be hidden until the parent task is completed?
Proposal: No. Child tasks should be visible, but appear as disabled. We could show disabled tasks by making the text grayer, and setting the CSS cursor option to not-allowed (cursor: not-allowed;).

+1

[KebabRonin]

@gabrielc

• The extension should ship with its own space + template.
• The space would be excluded from search, as to not pollute searches.
• When a user starts the tour with the “Create page” task, we automatically redirect the user to this space and make them create the page there (by clicking the “Create” button). The page created should use the provided template
• If the user skips the “Create page” task, we automatically create a page for them based on their username (e.g.: “Tutorial page for [USERNAME]”)

@gabrielc

Proposal: We achieve this by only giving view rights to the page, to the user that created it.

How I picture the Guided Tour Sandbox space (or whatever we’ll end up calling it):

• Rights: for all users, view rights are denied for all children pages
  • The USERNAME pages have view/edit rights enabled only for that user (I guess it’s similar to the existing User Profile pages)
  • How do we handle users not having edit rights on that space/entire subwiki? See bulletpoint below
• For making sure the rights are properly set up, there could be a warning, encouraging Admins to fix it either manually (!!), or with a button that automatically applies some config (to allow edit rights for users in the sandbox space)
  • Another option could be to ask for Admin consent for the Guided Tour application to create the pages for the users, in a workaround-y way around the edit rights - so users can practically create pages, but only according to the Sandbox rules (aka. they can only create a USERNAME page in the Sandbox space, and no other additional pages)
  • If Admins can fix the rights config manually, we’d need a robust way to validate the config somehow. What if Admins only want a special group to be able to have the Sandbox?
  • This sounds really similar to the Personal Pages proposal, which I’m not sure what happened to that idea

@gabrielc

Can / should this data be stored in the user page?

I’m not sure where else the data would be stored. Creating a new page with the same rights as the User Profile seems redundant, and having all user data on the same page seems bad. Idk if there are other options for persistence.

@gabrielc

Proposal: We wait for the DOMContentLoaded event, after that we start a 5-second timer. If the element doesn’t appear on the page after the timer, we discard the Task and show an error to the user, so they know something went wrong with the tour.

+1 for this, but it would imply a behavior change from the current Tour app. The current Tour behavior of a step that can’t find its target is to skip that step and go to the next one.
Skipping the task altogether, as you proposed, ensures that the original intent of the tour is unchanged. But there are also tasks like the Homepage tour, in which step order doesn’t really matter/they’re not dependant, can still (partially) function with a missing step.
We could also leave this behavior as an option (onStepElementNotFound: skip/close task/display error/something else) - but maybe later on as an improvement

@gabrielc

Proposal: If a user clicks on the backdrop / items other than the currently highlighted element, we discard the current task.

+0 . I think it really depends on how tours/tasks are intended to be used: either stricter, more on-rails experiences, or more ‘relaxed’ ‘do this if you want’ suggestions.
For me, I find it hard to ignore the task step popup once it’s open, in order to go do something else on the page. Since the popup stays visible on screen, even if you scroll the page.

@gabrielc

Proposal: We only validate the currently running task.

I think it’s ok like this for 1.0 . It would be nice to dynamically complete tasks based on user action, but I think that should be another proposal (maybe along with a hint system ).

@gabrielc

Proposal: After the user finishes a task, we ask them if they’d like to start the next one.

So we’d need to have a way of specifying a (partial) task order, or a ‘redirectToTaskOnFinish’ property on each task, so the tasks are suggested in a particular order?
Would the ordering of ‘tasks which have dependencies are always lower than their parent tasks’ be enough?
Could tasks depend on multiple parents? Is this a feature we want?

• like: you need to do the create an AWM app task and add a new user on the wiki (from Admin section) task before you can unlock the ‘using AWM apps’ task - this is a rough example
  Could tasks depend on completing unrelated tours?
• like: Completing the Admin Section tour (which would be a default tour) would unlock some more ‘advanced’ tasks in some other application’s tour

@gabrielc

Should child tasks be hidden until the parent task is completed?
Proposal: No.

+1 . Hidden tasks could be interesting, but that’s for another proposal (and not 1.0)

@surli

We should have ways to easily migrate existing tour, as much as possible, but I agree we don’t need a strict feature parity.

So we would need some migration script as part of the app? Or just have it be possible to migrate, if someone wants to write a script themselves?

[gabrielc]

@surli

In such scenario if the element doesn’t appear it would be a bug, I’m not sure to see why you’d discard the task though: maybe the bug happens in some specific condition and it would be ok after e.g. a restart of the wiki? Or maybe you don’t have same meaning than me for “discard the task”? If it’s only temporary it’s ok.

I wrote it incorrectly. Apologies for the confusion! What I meant is the current task progress should be discarded, not the whole task. The user should be able to restart the task after.

@surli

Also the 5sec timer feels like quite a lot, I’m not sure we’d need this but I’m not against either.

Valid concern. The actual value of the timer could be changed. I wouldn’t have anything against that.

@surli

So the standard way of dealing with this kind of thing is the following timeline:

1. the code is provided in XWiki Standard repositories (xwiki-platform here), but the extension is not bundled. The extension can be installed as any other extension, but we inform in the extension page that it’s still exploratory
2. When the extension is ready, we bundle it and we move Tour to contrib, and we stop bundling that one

So for now the new app won’t be bundled.

Thank you for the clarifications!!
This is really helpful.

@KebabRonin

+0 . I think it really depends on how tours/tasks are intended to be used: either stricter, more on-rails experiences, or more ‘relaxed’ ‘do this if you want’ suggestions.
For me, I find it hard to ignore the task step popup once it’s open, in order to go do something else on the page. Since the popup stays visible on screen, even if you scroll the page.

Good point. I think that in the config page of the extension, users should be able to customize the backdrop of a step as well (color, transparency).
TBD how this should be done.

@KebabRonin

So we’d need to have a way of specifying a (partial) task order, or a ‘redirectToTaskOnFinish’ property on each task, so the tasks are suggested in a particular order?

In the mockups made by Thiago, at the end of a task, a modal would appear asking the user if they want to explore on their own, or continue with the next task. Example below:

@KebabRonin

Would the ordering of ‘tasks which have dependencies are always lower than their parent tasks’ be enough?

At least for now, the modal asking the user to start the “next task” would only appear for “Getting Started” tasks. Since we are the ones creating the “Getting Started” tasks, we can ensure the order is correct, during development.
Tasks created by extensions, should be displayed in the widget, and can be started at any time by the user. If a task depends on another task, it would be disabled until the parent task is completed.

@KebabRonin

Could tasks depend on multiple parents? Is this a feature we want?

I’d say that a task should only be able to depend on 1 or no tasks. At least for now. I think it would be quite an advanced feature, and I’m currently not sure if the amount of users needing this type of feature (if any) would justify its development.

Thank you everyone for the feedback!!

[ChiuchiuSorin]

@gabrielc

Behavior for missing target element

We can make DriverJS wait for an element to appear on a page, then the library would bring focus to that element. What should happen if, for whatever reason, the element doesn’t appear on the page?
Proposal: We wait for the DOMContentLoaded event, after that we start a 5-second timer. If the element doesn’t appear on the page after the timer, we discard the Task and show an error to the user, so they know something went wrong with the tour.

+1, but I also agree that the 5 seconds feels like too long.

@gabrielc

Define backdrop click behavior

In Thiago’s mockups, the backdrop is transparent, only the popup is visible. This means that users may click on elements other than the highlighted element. How should we handle this?
Proposal: If a user clicks on the backdrop / items other than the currently highlighted element, we discard the current task.
Before we discard the current task, we show the user a modal, notifying them that they’ll lose their progress if they continue with the action they’re trying to perform. This way we prevent users from losing progress because of accidental clicks outside the highlighted area.

+1, but with the added idea to be able to customize the backdrop interaction.

@surli

I’m not sure: I would prevent users from leaving the current page, but I wouldn’t forbid any click any where else. For example, if the action is about clicking an entry in the “more actions” menu, I wouldn’t necessarily forbid the user to click elsewhere, as long as they open back the more action menu to click on the highlighted item. But that’s debatable.

-1
I’m not sure it would be best to let users interact with elements outside the highlighted area. How I see it, the tour should guide the user through specific interactions, or showcase specific functionalities. Allowing him to interact with any elements could lead to a changed context which could potentially break the tour.

@gabrielc

What happens when a child task is done during a parent task (e.g.: during the “Create a page” task, a user inserts an image on the page)?
Proposal: We only validate the currently running task. For example, if the user inserts an image on the page during the “Create a page task”, at the end of the task we only validate the “Create a page task”. The user could then start the “Insert an image on a page” task, and insert another image, or they could decide to skip the task entirely. We leave it up to the user.

+1

@gabrielc

For example: If the user already finished the “Create a page task”, they could choose to start the “Add a comment” or “Insert an image on a page” tasks, in whichever order they want. If the user didn’t do the “Create a page” task, the child tasks will be locked until they finish the parent task.

What would be the flow when a user selects a random task from the task list widget? Will the next task start automatically? Will the user be redirected to the first task not yet completed?

For example, from Thiago’s mockup: if a user after he creates the page and unlocks the rest of the steps decides to do Upload an attachment, after he finishes the task will he be redirected to Leave a comment, or Insert a macro on a page? Or should we have the Explore by myself option (which I assume stops the tour?) and a previous / next task buttons?

@gabrielc

Should child tasks be hidden until the parent task is completed?
Proposal: No. Child tasks should be visible, but appear as disabled. We could show disabled tasks by making the text grayer, and setting the CSS cursor option to not-allowed (cursor: not-allowed;).

+1

@gabrielc

@gabrielc

• The extension should ship with its own space + template.
• The space would be excluded from search, as to not pollute searches.

Proposal: We achieve this by only giving view rights to the page, to the user that created it.

+1
Maybe we could create a dedicated template and automatically set the view rights only to the author.

[gabrielc]

@ChiuchiuSorin

What would be the flow when a user selects a random task from the task list widget? Will the next task start automatically? Will the user be redirected to the first task not yet completed?

For example, from Thiago’s mockup: if a user after he creates the page and unlocks the rest of the steps decides to do Upload an attachment, after he finishes the task will he be redirected to Leave a comment, or Insert a macro on a page? Or should we have the Explore by myself option (which I assume stops the tour?) and a previous / next task buttons?

If the user selects a random task, after completing it, the task is marked as checked and progress is added to the progress bar. The modal doesn’t appear anymore, and the user isn’t directed to do any other action.
If the user discarded the modal once, it shouldn’t appear again. At that point, the order in which the tasks start, or if they start at all, is up to the user.
The rationale is that if the user wants to explore on their own, we should allow them. We shouldn’t be pushy. But if they decide they do need some help, the tasks would still be easily accessible.

[KebabRonin]

So the extra step with ‘Explore by myself’ would be more like an extra step which is part of the ‘Create a Page’ tour, and not some automatic popup which should show up for all tours/tasks implicitly?

I’m asking whether to:

1. treat is as a regular step (so you have to create it yourself/copy it from an existing task if you want it at the end of your task)
2. treat it as a basic guided tour functionality (like you have a checkbox whether to include the extra ‘Explore by myself’ step in the tour, with some options for the skip/accept/description texts).

From end-user UX point of view both options above should lead to the same outcome, the question is about how to handle it on the task-creator-user UX/backend side.

In my opinion, (1.) treating it as a regular step would be more modular, as it wouldn’t introduce a new type of step to keep track of in the app. To make it more usable we could add step templates for the task-creator-user, but that seems a bit overkill for a feature most users don’t use.