Extension:GuidedTour

Background
Our communities were once limited to using static wiki pages, templates, and other functions to build tutorials and tours of any kind. As rich as tools like Wikipedia:Tutorial might be, they interrupt the user and force them to go to a separate Web page. They are also quite long; most documentation about Wikipedia would take quite some time to read in full.

User experience
Interactive guided tours provide a simple, step-by-step guide through a feature set without interrupting the user. Guided tours don't dominate the screen, are dismissable, and walk the user through a task directly. Guided tours are also ideally something that one can return to at any time when you need it.

Each step in a guided tour is called a "guider."

Description of guider elements

 * Title: Names the current step. If the title is the beginning of the tour, you may need to use it to describe the tour as a whole. If your tour title is more than one line, it's too long.


 * Body text: Describes the current step. If you make additional points unnecessary for the user to understand how to move to the next step, you're saying too much. Guided tours are effective not just because tooltips point at things, but because they limit instructional text to what is immediately necessary, rather than trying to dump paragraphs of documentation on a user all at once.


 * Buttons: tour buttons are for actions, typically progressing the user to the next step. By default, guided tour buttons use the "progressive" class from the mediawiki.ui library. It is a poor practice to provide multiple action buttons, e.g. "Start tour" plus "Next." Choose one action you want the user to take in response to a tour step, focus on completion of that action. Never use the action button for ending the tour (unless the user is actually at the end), since this muddles whether the primary action buttons is for continuing the tour or ending it (positive vs. negative action). If your guider step points to an additional action you want the user to take (e.g. "Edit" or "View history), it is a bad idea to have the tour button perform this action for them. Instead, point to the element you wish a user to use, and encourage them to give it a try, so they learn how to use a function as they normally would.


 * Close button (X): provides an obvious element for dismissing a tour, as opposed to simply closing a single guider, which can be done by an outside click or hitting ESC. If the user clicks this close button, it should end the tour across pages, and will clear the associated tour from the user's cookies.


 * Location: Guiders can be positioned as either a "central overlay" or an "attachment". "Attachments" are positioned next to specific page elements (for example, a link or tab) using CSS selectors. The position of the guider relevant to the page element is specified with orientations such as topLeft, top, topRight, rightTop, right, etc. (See details)

Description of guider behavior
Keep in mind the following default behaviors for guided tours:
 * If a guider is not visible (i.e. above or below the fold) for a user, the browser will scroll the user to the location of the guider. You can choose to disable this for individual steps.
 * Guiders animate in to view by default, unless it requires scrolling to see. Animations can be disabled if you are writing a tour.
 * If a user has launched multiple tours, the most recent tour started will always be displayed, if there is a conflict.
 * You can force a tour to "stick" to a particular page. If you have not defined this behavior in your tour, a tour in progress might keep showing across pages. For instance, if you have a tour that points to the "Save" button, a tour that is in progress might point at this element every time until the user moves to the next step or dismisses the tour.
 * A guider will flip horizontally to the left or right, if it would otherwise be cut off by the width of the user's browser. You can also disable this for each step.

Designing a tour
If you want to make your own guided your, here are some maxims to consider.


 * 1) Choose a primary goal for the tour. What do you want users to learn by the end?
 * 2) Know who your audience is before you start, and what their goals and experiences are. What knowledge about a process do they have before starting your tour?
 * 3) Plot the necessary steps, focusing on the one action or key takeaway for each step. Less is more. The more steps in your tour, the more likely a user is to abandon your tour in the middle.
 * 4) Tours can be started via a link or button within a page, or automatically via a cookie. How you start a tour has a big impact on the potential for delivering tours that interrupt or annoy users, so choose carefully.
 * 5) Let the steps and their associated actions guide the design of the tour. For example, if you want users to edit as one step, pointing directly to the edit button is the obvious and efficient thing to do. A poor alternative would be to have a center-aligned window with an image and description of the edit tab. The strength of tooltip-based tours is that you can show users what to do, instead of simply describing it.
 * 6) Choose titles, body text, and images only after you have plotted all steps in your tour.

GuidedTour
The following tours are currently packaged with the extension, and are thus available on any wiki where GuidedTour is installed.


 * Test - Simple tour to show what tours can do (, demonstration).
 * First edit - A tour showing you how to make your first edit using the wikitext (, demonstration) editor or VisualEditor (, demonstration).

Other extensions

 * GettingStarted - A package of simple tours to help the users complete the onboarding process. There are versions for both wikitext  and the VisualEditor.

On-wiki

 * The Wikipedia Adventure - this project is a pilot of a game-like experience for learning the ropes, hosted at The Wikipedia Adventure on English Wikipedia (Level 1 Code).

Feel free to add your own tours to the appropriate list above.

Find more examples by searching for "prefix:MediaWiki:Guidedtour-tour", e.g. at Enwiki.