Follow up for #1920468: Write a tour for the first page after install showing extend and other things


Tour is neat. Having tour and help separate might be confusing.

Proposed resolution

Replace help (or advanced help) with tours.

Remaining tasks

Discuss, and better define the problem motivation.

User interface changes

Yes. changes to help.

API changes

No API changes anticipated. (?)

#21 drupal8.tour-module.1920470-21.patch570 bytesclemens.tolboom
#19 drupal8.tour-module.1920470-18.patch1.59 KBclemens.tolboom
PASSED: [[SimpleTest]]: [MySQL] 58,446 pass(es).
[ View ]


nick_schuch’s picture

Component:other» tour.module
LeeHunter’s picture

Issue tags:+docs infrastructure
LeeHunter’s picture

Issue tags:+d8docs
aspilicious’s picture

If JS isn't allowed on a system for any reason tour is useless. So I'm not sure it's ok to just drop it.
But in the end I don't realy care.

nick_schuch’s picture

I believe the correct way to handle this is to also have a non js version. I was considering some type of list at the top of the page. But that this is a work in progress and needs more fleshing out.

tim.plunkett’s picture

We could have the tour data added directly to the "help" region as an ordered list, with .js .tour-wrapper { display: none; } or something.

batigolix’s picture

Cross linking to the meta issue that oversees the update of all core hook_help help texts:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

batigolix’s picture

Currently the help texts contain a kind of "quick overview" information regarding the modules that are included in Drupal core.

Tour, as far as I can see, provides explanation on page elements (input fields, submit buttons) level.

It is not so easy to restructure and rewrite the existing hook_help texts to become useful Tour tips.

Another related and relevant discussion is if Tour tips should be included in core at all:

jhodgdon’s picture

To expand on #8...

It seems like hook_help() is probably still appropriate for the Module Overview type of help, which explains in general what a module is/does. Assuming we want such help to exist (and I think we do?), text is an appropriate presentation, in my opinion.

hook_help() is also used for page-specific help text, and this may be more appropriately done with Tour, at least in some cases... I am not too sure though. Sometimes hook_help() (or a textual presentation) is probably still good. For instance, take block_help() in D7:!block!block.module/function/blo...

This is being used on the admin/structure/block/add page to note the purpose of the page (which may or may not be necessary, but there it is), and on admin/structure/block/list/* to give a quick overview of the purpose (again, text is good if it's necessary at all), explain how to use the page (Tour could be better for that but concise text is quicker to scan -- maybe need both?), and to provide a link to the demonstrate block regions page (not appropriate for Tour at all).

So... maybe we need both? I don't think Tour sounds like a replacement for Help to me.

nick_schuch’s picture

I definitely feel that this is a great discussion to be having.

I believe we are going to need them both. But that's not to say that we can't use the documentation that is provided in help module to produce some great tips and elevate some of the work that help module does.

We are currently working on fleshing out tips for core in this ticket: #1921152: META: Start providing tour tips for other core modules.

This META might add some clarity to this discussion as it progresses.

chrisjlee’s picture

I think the help module isn't too helpful.

It should only be used as a means of looking looking for readme file or multiple readme files within a module/theme folder.

Or what would be very cool is if it notified you if the readme has changed.

Just my 2c's!

yoroy’s picture

Title:Replace help with tour» Find out how help and tour can work together

To me then the discussion should not be about replacing one with the other but a good look at which parts of the current help system would benefit from being reworked into a tour for a given page.

batigolix’s picture

To expand on #8 & #9:

The Tour API allows for general introductions to be included in the tour. In the config file they look like this:

    id: introduction
    plugin: text
    label: Adding or Editing a container
    body: <p>This form can be used to edit an existing container or add a new container to your site.</p><p>Containers are used to group forums together. For example if you ran a Drupal forum you might create a 'Support' container and include forums for 'Installing Drupal' and 'Getting started' inside the 'Support' Container</p>
    weight: "1"


This introduction is not bound to any element and is shown at the start of the tour (I suppose) when a user clicks the help icon.

This introduction could be a good place to move the hook_help information to, although sometimes hook_help tends to be a bit longer than you would wish for the start of a tour, but we could work on that.

I did some tests with the tour introduction tips but could not manage to get it to work, but that may be the subject of another issue.

I doubt if we should allow these two competing help systems together in core.

jhodgdon’s picture

So... hook_help() is currently being used for two different things:

a) The module overview pages. I don't see exactly how these would be done in tours, since they don't apply to a particular admin page, and I don't think they are really "tours" but really background information. I think this still belongs in hook_help().

b) Help explanations for particular admin pages. These would probably be good as Tours.

clemens.tolboom’s picture

As mentioned by me in #1921152-57: META: Start providing tour tips for other core modules. we have system oriented and task oriented ways of explaining stuff.

hook_help() states

Provide online user help.

By implementing hook_help(), a module can make documentation available to the user for the module as a whole, or for specific paths. Help for developers should usually be provided via function header comments in the code, or in special API example files.

which I read as system level and partly task oriented as module path can have help explained too.

Having a multipage tour on the other hand could make a task oriented guide.

But both lack skill level support like "I'm a novice". Let alone task based skill level as in "I have done this before so now I'm an expert".

Is tour to early in core?

nick_schuch’s picture


I don't feel that now is the time to be discussing "Is tour to early in core?"

Can you please provide use cases for the "I'm a novice" and "I have done this before so now I'm an expert" scenarios. Then I can be more help.

clemens.tolboom’s picture

@nick_schuch I'll answer the novice versus expert in #1921152: META: Start providing tour tips for other core modules. as we already started there.

jhodgdon’s picture

Status:Active» Closed (works as designed)

Actually, I think this issue has pretty much served its purpose. We've clarified that hook_help() is still needed to provide a textual overview of each module, and to provide summary text at the top of admin pages. Tours are also useful, to provide an interactive introduction to doing tasks. Let's just close this issue, because I think we all agree that tours and help are different, and they don't really duplicate each others' functionality.

Please continue discussions of what tours we should put into core on
#1921152: META: Start providing tour tips for other core modules.

clemens.tolboom’s picture

Status:Closed (works as designed)» Needs review
new1.59 KB
PASSED: [[SimpleTest]]: [MySQL] 58,446 pass(es).
[ View ]

Bojhan asked me for a list of tours a user could autostart.

We could do so by implementing hook_help() for tour which the attached patch does. It's result is like this:

Available tours.

  • Block (5):
  • Custom block edit (2):
    • block/*
  • Custom blocks list (2):
    • block/*
  • Views ui (10):
    • admin/structure/views/view/*

Trouble is not all path are complete. Probably most are not.

The patch does not use any caching so is slowing down /admin/help and /admin/help/tour so needs work if this is a step forward.

jhodgdon’s picture

Status:Needs review» Closed (works as designed)

Please put this on the other issue about making tours, or on this issue about adding hook_help() to the Tour module:
#2035145: Create hook_help for Tour module

clemens.tolboom’s picture

Status:Closed (works as designed)» Needs work
new570 bytes

@jhodgdon I'm not sure this issue has an up to date summary.

Furthermore we could add a last tip to every tour based on it's module the tour belongs to. That the other way around for #2035145: Create hook_help for Tour module

Attached patch needs work but now safely blocks #19.

The main puzzle is to decide what value for hook_help($path) we want to use.

Feel free to re-close if the idea is too bad but I think this could integrate both systems nicely.

jhodgdon’s picture

Seems like a reasonable idea.