Learning patterns/Creating Guided Tours together with the Community

A learning pattern for"online engagement"
Creating Guided Tours together with the Community
problemNew users of Wikipedia often need to search for introductions in a very time-consuming way and are unable to find a solution on help pages quickly. To support them with guided tours, we aim to describe in this learning pattern how guided tours for new users can be created in cooperation with the community and with minimum effort by engaging the help of an external service provider.
solutionCreating Guided Tours together with the Community
created on19 February, 2018

What problem does this solve? edit

New users of Wikipedia often need to search for introductions in a very time-consuming way and are unable to find a solution on help pages immediately – if they find the help pages at all.

There are hardly any tools that offer an easy introduction to editing Wikipedia and provide help to users precisely when they need it. In such cases, guided tours can help new users in Wikipedia by providing interactive help, either in addition to, or instead of, help pages. The guided tours fill a gap in the help spectrum between the independent search for information and the guided help provided by mentors or trainers.

To create such a tour, a lot of information has to be collected and structured (e.g. Help: guided tours, Extension: GuidedTour, Write an on-wiki tour). This learning pattern is intended to support the creation of such a guided tour and to show the individual steps in the process, e. g. communication with the community or how the external programming of certain steps can be commissioned.

What is the solution? edit


Within the framework of campaigns to attract new authors (annual plan: Focal Point 1),  Wikimedia Deutschland, with the support of the community, conceived and implemented an introductory tour aimed at users who have just registered and are getting acquainted with Wikipedia. The following descriptions are based on this project and provide a step-by-step overview of how a guided tour can be implemented in cooperation with the community.


Guided tours are a Mediawiki feature based on the Extension: GuidedTours and are available in many wikis. For guided tours to work, this extension must be installed in the corresponding Mediawiki as is the case in the German language Wikipedia. By adding the following extension (text) to your Wikipedia link, you can start a test guided tour and test whether this extension is installed in your Wikipedia: ?tour=test

(e.g. https://de.wikipedia.org/wiki/Mister_Undercover + ?tour=test = https://de.wikipedia.org/wiki/Mister_Undercover?tour=test)

If it is installed, a test tour will be retrieved.

To create a guided tour, you should schedule approx. 8 hours of plane programming work plus additional time to allow for community input and coordination. The following things are  required before you start programming:

  • Basic knowledge of Javascript or HTML
  • Wiki experience
  • Support of the community where the tour is implemented

This knowledge can be provided either by an external service provider or a community member.

Content implementation

In this step we describe how we worked together with the community to create the different steps of the guided tours. We first decided on the topic of the guided tour: As part of the campaign to recruit new volunteers, we wanted to adapt the guided tour to the needs of newcomers.

Then we published some useful steps on our project page for new volunteers in the form of a table and obtained feedback from the community. In order for the community to get an impression of guided tours, a test tour should be made available to the community during the content implementation period. A link of the current wiki page with the above-mentioned add-on (e. g. /Wikipedia/Article? tour=test) is suitable for this purpose.

The following steps for the tour resulted from this communication process and were subsequently developed in collaboration with the community and subsequently implemented:

  1. Welcome to Wikipedia
  2. Articles
  3. Discussion
  4. Editing
  5. Edit source code
  6. Versions of an article
  7. Your user page
  8. Help for authors
  9. Questions from beginners
  10. Mentoring program

After the steps were clear, explanatory texts, which appear in each step of the guided tour should then be jointly created with the community. Before the guided tour can be programmed, you also need to decide where the text boxes of these explanatory texts should be displayed on the wiki page. Below is an example of some of the texts and text locations that we had on our wiki page to discuss with the community:

Location Heading Explanatory text
Overlay Welcome to Wikipedia This short introduction shows you the most important buttons to help you find your way around faster. You can quit at any time and come back later.
Button: Articles Articles You are currently on an article page, i.e. the encyclopedic item.
Button: Discussion Discussion Each article includes a discussion page where suggestions for improvement are discussed with others. Before you make any changes to the content of an article, you should always check the discussion page first to see if there are any comments. You will also find other users there who are interested in the article’s topic.
Button: Editing Editing Click this button to switch to edit mode. You can edit the page as you would in a word processor and then save it.
Button: Edit source code Edit source code Here you can directly edit the source code. The basis is a simplified form of HTML, called Wikitext or Wiki markup. It may seem a bit complicated at first, but it just requires some practice.

With this information everything is in place to start programming the guided tour.


These texts and positions must then be converted into Javascript. The description of how to write an on-wiki tour, to be found on MediaWiki, must be forwarded to either an external developer. Example tours can also be used as a basis for the implementation. The completed guided tour can then be saved either in the extension or in the MediaWiki code. In our case, we decided to save them in the Mediawiki. A .js-page is created by a Wikipedia administrator, which contains the Javascript code. If this code has been written by an external service provider, it must then be saved by a Wikipedia admin as a .js-page. The filename must start with "Guidedtour-tour-Name.js", whereby the name must correspond to the name of the guided tour. For example, if the tour has the name "test," the file must be named: Guidedtour-tour-test.js. As soon as the file is saved in this way, the tour can be used.

Implementation of the tour

To initiate the tour, you can add the name of the tour to each wiki URL. It is also possible to create a button for individual tours and to start the tour via the button. In this case, the button leads to the corresponding URL of the guided tour, i.e. it is played back via a wiki URL. Here, the following extension had to be added to the link:"? tour=einfuhrung".

Because the tour is integrated in Wikipedia, users at the end of the tour (or when they actively finish the tour) are on the page they last visited (within the tour). This means that no change is made into another wiki environment or project.

Things to consider edit

The tours can only be created by admins. In addition, this is a big interference with the wiki, which is not possible without the consent of the community. The following is therefore necessary:

  • Interact with the community and coordinate the project with them
  • Get admins involved about the project (only they can create code in MediaWiki)
  • Provide tours in a test wiki and invite people to comment
  • There could be some complications with the Getting Started Extension in MediaWiki. The solution to these problems requires a deeper reconfiguration of this extension and therefore could not be implemented yet. If the problem occurs, however, depends on the wiki.

Guided tours can generally be used on most pages. On the following pages, however, they cannot be used for security reasons: Login, create user account, reset account settings and password.

See also edit

External links edit

Here you can find the script for the guided tour we created:

Here is an example of the Wikidata guided tour:

Here you can see another guided tour (Wikipedia:GettingStarted):

Here you can examine the guided tour Extension of the Mediawiki:

References edit