Guided Help Tours in Drupal 8 (sort of)

One of the neat new things in Drupal 8 is something called the Tour module. It is built on the Joyride jQuery plugin, which provides a clickable tour of HTML elements on your website. It gives you a way to walk a new user through your site or a particular interface with text instructions and next buttons. If you're not sure what this all means or looks like, have a look at the video below to see it in action in Drupal 8.
 
I was drawn to investigating the Tour module because I love ways of helping people through documentation. The Drupal core help system is an old system, and there have been many discussions and attempts to update it in the past. Tour certainly doesn't replace the help pages at this point, but it is an interesting new tool. So what exactly is going on with it in Drupal 8? Will we have a fancy new tours all over a default installation? Well, no. As it stands right now, there is only one tour in Drupal 8, which is for the Views building interface. It was submitted as a proof of concept with the Views module in core. So what's the deal?
 
Let's start by understanding what we have in core right now, and then I'll discuss some of the next steps that need more work. We currently have the Tour module in Drupal core, and that provides us with the Joyride plugin and a Drupal API with which to use it. We also have that one sample tour in the Views module. At this point you need to write your own module to add more tours to core. That's it for right now—in core. However, there are two contributed modules in development that integrate with the Tour module: Tour UI and Tour Builder. The Tour UI provides a basic user interface for Tour module ,and Tour Builder extends that further to let you use the interface to create a new tour, export that as code, and share it with others. Both of these modules are not up-to-date with the latest version of core, but once Drupal 8 settles down, and these modules get updated, these should be great tools to help usage of Tour.
 
 
There are quite a few tickets for some additional features to be added to Tour, like multi-page tours, adding role-based access to the tips, and a new tip notification system. There are also a lot of tickets for different kinds of tours that need to be written and submitted as a patch for core. You can find all of the ongoing work in the core issue queue, tagged with Tour. When it comes to actually creating tours though, our delay is based on a community documentation problem, not really a technical one. You can read the long meta issue that discusses many aspects of using Tour in core if you want the full backstory. At the end of the day, a lot of work has been done to document the general idea, but for each of the tours to be created there still seems to ongoing discussion about the best use of them. Here's what I've found so far in my own journey to understand the next steps.
 
There are a number of guidelines for when and how to write tours, but for many people the purpose and correct implementation of the tours is still not quite clear. There are three pieces to grok to create core tours right now:
 
  1. UI Patterns for Tours: this page describes the use cases and general principles for how tours should be used.
  2. Tour Text Standards: this page gets into the actual text of the tours and the things you should keep in mind while writing them.
  3. Tour API in Drupal 8: this is the required documentation to actually write the code to create a patch for Drupal core.
 
I dare say that once people can agree on the correct usage of the Tour module, and start writing them out, that getting developers to help turn them into code will be a pretty straight-forward process. Again, this isn't a technical problem really. We need to be clear about why we introduced Tour into core, and how we expect people to use it so folks can dive in to actually using it. It would be a sad thing to have the API in core, but not much implementation to actually help the end users that it was intended for.
 
Related Topics: 

Comments

Add new comment