Extension:GuidedTour

MediaWiki extensions manual - list

GuidedTour Release status: beta
Implementation	Special page, Page action
Description	Provide popup guided tour on wiki pages
Author(s)	Luke Welling, Matt Flaschen, Terry Chay
Last version	0.9.0 (2012-12-03)
MediaWiki	1.21+
PHP	5.3+
Database changes	no
License	Apache 2.0
Download	Follow installation section.
Hooks used BeforePageDisplay MakeGlobalVariablesScript ResourceLoaderTestModules
Check usage and version matrix
Bugs: list open list all report

Wikimedia Foundation engineering activity

Guided tours

Create infastructure for providing guided tours, as well as some initial tours

Group:	Editor Engagement experiments
Start:	2012-09
End:
Team:	Munaf Assaf, Terry Chay, Matt Flaschen, Ori Livneh, Maryana Pinchuk, Steven Walling, Luke Welling
Management:	Terry Chay
Status:	See updates

Guided Tour is a MediaWiki extension that allows the creation of guided tours using a variant of Optimize.ly's Guiders. It is developed by the editor engagement experiments team. It originally started at WMF Tech Days 2012.

Rationale

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. Guided tours are listed in our feature map as a potential as a tool for new editor support.

User experience

Test tour, step one. An example of a typical tour start.

Test tour, step two. An example of calling out a page element.

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.

Description of guider elements

Title

Describe 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

Use body text to describe the current step. If you find yourself adding in several 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. They're effective because they help 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. 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). This muddles whether the primary action buttons is for contintuing the tour or ending it (positive vs. negative action).

Close button (X)

the purpose of this to provide an obvious choice 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.

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. Remember that 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.

List of tours

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.
• gettingstarted - Tour to help the user make their first edit. The primary test case will be for Extension:GettingStarted, but is very close to being a general "make your first edit" tour. This tour is a product of the requirements for our onboarding new Wikipedians project.

Tour ideas

Potential tours include nearly all tasks currently covered by help documentation in Wikimedia projects. We're starting with Wikipedia, and with tasks that are most common or attractive to new registered editors, since they are a group most likely to need a guided tour of an interface or activity.

• The edit window aka 'make your first edit'
• Page creation
• 'Your user page' - what it's for, etc.
• Watchlist - what are the important elements of it, how to add stuff to it, etc.
• Specific types of edits, such as for the backlogs of copyediting, adding links, and other activities.
• Process helpers: how to request a move, how to file a deletion request, etc.

Please add to the list!

Technical documentation

We're building guided tours with the Guiders.js library (github, Local Guiders branch). Guiders is under an Apache 2.0 license and has been used by WordPress, Drupal, and others. We incorporate the Guiders library into an Extension:GuidedTour, and can feed changes upstream. If you'd like to help out or follow progress, you can check Bugzilla.

Building and launching tours

You launch a guided tour on a page by adding tour=tourname to the query string of a URL linking to it, or by calling mw.guidedTour.setTourCookie( tourName ) to set a cookie for the next page load. You can set the cookie from the server if appropriate too. This will cause the GuidedTour extension to load both the code to display the tour and the tour itself.

You define your tour in an extension, or in the MediaWiki namespace (MediaWiki:Guidedtour-tour-tourname.js). Individual wikis can override the CSS at MediaWiki:Guidedtour-custom.css.

• To add a tour by editing your wiki, see /Write an on-wiki tour
• To bundle a tour with your extension,see /Write an extension tour
• For API documentation, see http://e3doc.wmflabs.org/GuidedTour/#!/api/mw.guidedTour

Installation

1. Open a shell and navigate to your extensions directory.
2. Run:

   git clone --recursive https://gerrit.wikimedia.org/r/p/mediawiki/extensions/GuidedTour.git
   

3. Add the following lines to your LocalSettings.php:

require_once( "$IP/extensions/EventLogging/EventLogging.php" );
require_once( "$IP/extensions/GuidedTour/GuidedTour.php" );

Test that it worked by calling a page with tour=test appended to the URL. For example: http://localhost/w/index.php?tour=test

Usage

1. Write a real tour on a page in the MediaWiki namespage. It must be named MediaWiki:GuidedTour-tour-tour name.js, for example MediaWiki:GuidedTour-tour-mytour.js
2. Call your intended page with tour=mytour appended to the URL. For example

   http://localhost/w/index.php?tour=mytour , or ?tour=test for the example above.

3. To style the output, either edit the css file in the modules directory or provide a file of overrides on the wiki page MediaWiki:GuidedTour/custom.css

Dependencies

It depends on Extension:EventLogging, so that must be installed first.

Update with git

git pull
git submodule update --recursive

See also

• /Upstream change - If you want to make a change to upstream Guiders (see our clone of this here).

Subpages

GuidedTour/API brainstorming	GuidedTour/Microsurveys	GuidedTour/Shared tour instructions
GuidedTour/Shared tour instructions/doc	GuidedTour/Upstream change	GuidedTour/User testing
GuidedTour/Write an extension tour	GuidedTour/Write an on-wiki tour	GuidedTour/archive//tours/guidedtour/intro
GuidedTour/archive/Make your user experience easy to learn: a guided tour	GuidedTour/archive/tours/guidedtour/mypreferences	GuidedTour/archive/tours/guidedtour/starttour
GuidedTour/archive/tours/test/sample	GuidedTour/status

Status

(Regular status updates)

• [edit status] • [add new]
  2013-02-07:
  Matt Flaschen has created initial documentation for on-wiki tours.