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

Problem/Motivation

The Tour module is in Core, but we have very few tours in Core that use it.

Note: We actually are unsure whether Tours are actually beneficial -- Tour hasn't been usability tested (see comment #141).

Proposed resolution

* Decide what tours would be beneficial.
* Agree upon standards for tours.
* Create tours.
* Commit them to Core.

Remaining tasks

Task A: Decide what tours would be beneficial

Some ideas for tours:

  1. Initial Experience #1920468: Write tour integration for the first page after install showing extend and other things
  2. Blocks #1926294: Write tour integration for block_content.module
  3. Fields #1960824: Write tour integration for Field UI module
  4. Views - some done in #1809352: Write tour.module and add it to core (needs an issue to finish/polish the views part)
  5. Multilingual #1940590: META: Write a multipage multilingual tour (broken out into sub-issues for different module features)
  6. Appearance #2040375: Write tour integration for Appearance pages
  7. Structure #2040791: Write tour integration for Structure page
  8. Content #2040817: Write tour integration for admin/content
  9. Add/edit content #2044397: Write tour integration to add/edit content UI
  10. Menu #2040823: Add tour integration for Menu admin page
  11. Reports #2040833: Write tour integration for Dblog page
  12. People #2040845: Write tour integration for People page
  13. Extend #2040861: Write tour integration for Extend (Modules) admin page
  14. Edit user #2044399: Write tour integration for user edit page
  15. Shortcuts #2044407: Write tour integration for shortcuts page
  16. Forums #1926296: Write tour integration for forum.module

From comment #130 -- @xjm's idea: Some obvious candidates for tours:

  • Each tab of the Field UI (and explanation of the tabs themselves).
  • The Extend page.
  • The Block UI (although the work on Layouts might eventually deprecate this page).
  • The Workflow UI.
  • The Appearance page.

Other thoughts on what tours to create:

  • Modules that implement hook_help(). Can some/all of the content be converted to tips? #1920470: Find out how help and tour can work together
  • Modules with routes. If it implements a page then there is a good chance it will also want to provide tips.
  • Some pages may just need a hook_help() text (which goes in the Help block) rather than a full tour -- the help block doesn't require you to click on a Tour button to get the help displayed.
  • Creating a tour for an admin page should not be a substitute for fixing usability problems on the page
  • @yoroy's list of "conceptual criticals": http://yoroy.com/pieces/drupal-ux-conceptual-criticals

Check for
- open issues tagged with tour
- Tour module issues

B: Create tours

Each tour that we want to create should be given an issue (if it doesn't already have one; or un-postpone existing issues).

Here are some links about creating tours:

C: Update the standards for tours

We currently have 3 pages that talk about standards for tours. They haven't been reviewed recently, and should be:

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

larowlan’s picture

Added forum and custom_block

andypost’s picture

Suppose node module tips better to split into separate patches

andypost’s picture

Issue summary: View changes

Added forum, custom_block

Gábor Hojtsy’s picture

How do we write tips for stuff for the state before people enable a module. Eg to describe what are the multilingual modules useful for? Asking to figure out if we can really make use of this instead of solving #1917212: Add checkbox in installer to enable content translation (if in foreign language) directly.

larowlan’s picture

We haven't looked at installer integration yet.
Joyride does include a 'modal' tip that isn't tied to an element, but instead provides just a chunk of help.
But I think here, we do want this bound to the checkbox.
So I think some more work is required to allow tour integration with the installer.
In terms of where these would live, can the yaml live in the install profile?

larowlan’s picture

Oh, and I missed the point here - tour module isn't enabled that early!
So yeah we'll need to add the library in a different manner in the installer.

Gábor Hojtsy’s picture

@larowlan: no, the "problem" is when you install Drupal in a foreign language, Drupal assumes you want a single language foreign language website, while some people assume Drupal would install into a multilingual environment (eg. with content translation, etc). It installs instead into a single foreign language environment (translating software, but no language selectors and only one language, assuming you want to have a single French, Spanish, Japanese, etc. website). In user testing, we found people did not necessarily find it obvious that they then need to enable one more module to make their site support multilingual content. One of the possibilities to solve is to add an additional checkbox in the installer. Another one is to add some kind of tour to let the user know about their state and their options. Not sure where/how that tour would be set up though. I'd assume multiple scenarios would apply to adding tours to the modules page, eg. if you want to explain a recipe on how to set up a calendar or image gallery, those would need to start on the modules page. So not sure how best to cater for such a use case, if at all possible.

vijaycs85’s picture

@Gábor Hojtsy, if we are going to have a generic tour after installation (from 'visit your new site' page), then we can add one more step by checking the installed language != default (en) to explain "you have installed in ABC language however you need to enable foo and bar to support multiple languages"?

Gábor Hojtsy’s picture

That is a possible approach I guess.

larowlan’s picture

So I've started work on two more tip plugins.
One for 'First Install' and another for 'LOTE' which we can use here.
So that we can use these to create tours but that have no output unless the conditions match.

Will keep you posted.

larowlan’s picture

So here's an example of these plugins and an implementation of a tour with the lote tip type.

So when you first install and land on in a language other than English - and - you have a translated version of the tip in your active store (example in Afrikaans language attached - be sure to rename the file) you get the following - yes the styling is off but that's an issue with the toolbar and body css position.

Once I create a node, this tour is no longer visible.

Screenshot
Only local images are allowed.

larowlan’s picture

Status: Active » Needs review
Gábor Hojtsy’s picture

Ok, this is getting into a territory that we maybe should not discuss on a META issue(?).

larowlan’s picture

Yep, and I think we should be using the new conditions plugin api too.
There are already:

#1921544: Create a Current Path Condition
#1921550: Create a Language check Condition
#1921540: Create a User Role Condition

There is a lot of overlap between how block module uses those and how we need them to work.

klonos’s picture

Related: #397430: Implement cross-reference links that refer to logically closely related functions.

Is it a good idea to point people to the menu instead of the page where they can directly perform the action. So instead of:

To create content in languages other than English, you need to enable the "Content Translation" module. This can be done from the "Extend" option in the menu.

...we could have:

To create content in languages other than English, you need to enable the "Content Translation" module in the Extend page

eigentor’s picture

So I was wondering how to see anything that is yet in core. I don't get any tour content showing in Views. Is there an explanation how to do this?
Sorry for posting in this issue, but I did not find a better one.

larowlan’s picture

Hi @eigentor
To see a tour in action, head to admin/structure/views - enable one of the default views - and then click he edit link.
To see how this is built, look at core/modules/view/views_ui/config/tour.tour.views-ui-en.yml.

Thanks

Lee

LeeHunter’s picture

Issue tags: +d8docs

adding docs tag

LeeHunter’s picture

Issue summary: View changes

Update description to provide some defintion.

YesCT’s picture

Status: Needs review » Needs work

from #1920468-3: Write tour integration for the first page after install showing extend and other things @Bojhan points out:

This is definitely almost a "postponed" we should have a strategy for tour module, randomly adding tours is not what we should do - its likely we will start trowing usability problems under the rug.

So it is a remaining task here to have that discussion, lay out some guidelines and add those as we go to the issue summary in the section: Pointers.

YesCT’s picture

Issue summary: View changes

Updated issue summary, added link to add a post install tour (to show extend)

batigolix’s picture

Some questions that may get us started:

1. When to include tips?

This issue assumes that every module (with a UI, I guess) should have Tour tips.
Would that mean that tips should be available on *all* the administration screens of all modules? Or only the most important screens?
The views UI can serve as an example. Tips on the main view edit screen seem obvious, but what about the more obscure popups like "Query settings"?
As mentioned in #18: does the need for tour tips not mean that there are UI problems that should be addressed instead?

2. Where to include tips?

What are the criteria for adding tips to elements? I can, for example, see a simple form (do they still exist in Drupal?) having a tip for each field and button, but more complex forms such as the node edit form? Will there be tips on each field inside the vertical tabs? What is the role of already existing UI text as labels and descriptions if there are also Tour tips?

3. What to include in the tips?

What kind of information are we providing? Descriptive information? ("In this section you find this 'n that") or more instructive? ("Enter this 'n that. grab the crosshair and drag the table row to the desired location"). Or will it be left to the inspiration of the individual author what to explain?

The hook_help texts once were a collection of short documentation snippets varying from end-user-centered to developer-centered (with code examples). Some were long but most were short. It was quite an effort to standardize these help texts and include at least a minimal amount information about each core module. Without guidelines, we could end up with a similar situation.

I think the Tour module is a very nice addition for Drupal core as it will enable developers & site builders to create sophisticated solutions for their customers. But I do not, yet, see the added value of having tour tips as part of Drupal core itself.

batigolix’s picture

Issue summary: View changes

Updated issue summary with locale module issue

andypost’s picture

Issue tags: +D8MI

If we would like to provide a tips for core so there should be ability to allow them to be translatable!

Currently there's no way to translate config entities within install profile and probably on module enable like #1943468-2: Move Tags vocabulary to standard profile config demonstates

klonos’s picture

Issue tags: -D8MI

@batigolix, #19:

1. When to include tips?
This issue assumes that every module (with a UI, I guess) should have Tour tips.
...

Not "should" - but definitely "could" so the answer to that question could be:

Whenever there is need for them. A good example would be after closing a documentation/support request issue against a module. The "hype" on these issues (for example nr of followers/people asking the same question etc.). If module maintainers don't want to see their issue queues filled with the same questions asked over and over again or with "critical bugs" (that are actually regular support requests), then they should make sure that the next release of core (or their contrib module) ships with a well-written tour for their module.

Another example would be after results from UX surveys come out I guess. If there is no way to solve a usability issue (for example if solving it means breaking the API and thus solution is postponed for next major release), then the next solution for current release would be better documentation. The tour.module is a documentation tool ;)

2. Where to include tips?

If a thing can be explained in a really *short* sentence with as few words as possible, then I guess it can be a help text for an element. More "verbal" descriptions belong in tour.module balloons IMO. Also multi-step explanations that hop from element to element belong to Tour tips.

3. What to include in the tips?

See my suggestions for questions 1 & 2 above.

As for standardizing the way Tour tips are used, I thing we simply shouldn't. If something is unclear to people the way it is written or somebody feels it should be presented otherwise, then they can file a documentation issue against the respective module and whatever improvement is the outcome of the discussion will be available in the next release. Even that can be improved later on. I guess what I'm trying to say is that I consider/envision the Tour system as a live, dynamic, constantly-evolving thing. Like the documentation on d.o but hosted locally in each site. Perhaps even over time this will evolve to be an independently-updated part of Drupal, like UI translations.

I personally never consider "too much help" a problem but a feature. On the contrary I greatly value well-documented software and the "Help" button is my favorite in every application. Now, in D8 with the tour.module I believe that we've found a cool way to both have this information easily available (and intuitively presented) to new Drupal users and at the same time "hidden" so that it doesn't get in the way of advanced users. As a bonus, we allow site developers/admins to create their own tours to explain how the site works to their users/visitors.

For all the above reasons, tour.module belongs in core.

klonos’s picture

Issue tags: +D8MI

...didn't mean to remove the tag.

batigolix’s picture

Totally agree that tour should be in core (it already is, so it is not really the issue here).
I just have doubts about including the tips (the .yml files ) in core.

Gábor Hojtsy’s picture

@andypost:

If we would like to provide a tips for core so there should be ability to allow them to be translatable!

Currently there's no way to translate config entities within install profile and probably on module enable like #1943468-2: Move Tags vocabulary to standard profile config

I don't get this. The configuration system where the tour .yml files are stored does support translation. With #1935120: Unusual language use in tour module fixed, tour module uses the system as intended (with language overrides), so there is even test coverage to demonstrate it works. With #1935094: Create configuration schemas for Tour module and #1905152: Integrate config schema with locale, so shipped configuration is translated, the tour files will get schema coverage and the locale system can identify translatable strings and you could even translate tours using the locale UI/API. I don't see what is missing for config entities or tour to support this really.

nick_schuch’s picture

I had a discussion with Bojhan this morning. These are the notes from that meeting:

- Bojhan recommends that we define a pattern for tour tips creation eg. http://drupal.org/node/1087100
- We should compile a list and target major core items first (Views, Field UI etc).
- Bojhan is going to bring up Tour in the next UX meeting.
- Tour UI to be in contrib. (http://drupal.org/node/1921188)
- Multi Page will be tackled if required but will required a lot more work. (Possibly in a Field UI tour).
- Regular meetings are going to be setup to track progress (roughly once every 2 or 3 weeks).

dcmistry’s picture

Update from the UX Happy Hour

We had a discussion on the UX happy hour to talk about the matter at hand. After a cordial discussion, we have come up with the following list (in order of importance)
1) Initial Experience
2) Blocks
3) Fields
4) Views
5) Multi-lingual (when module is enabled)

dcmistry’s picture

Issue summary: View changes

added link to issue

YesCT’s picture

FileSize
76.69 KB

updated the issue summary with the priorities from #26 http://drupal.org/node/1921152/revisions/view/2605572/2612212

issues need to be opened for some of the items.

we need clarification on number 5.
there are three modules that make up multilingual.
should we make one issue and identify all the pages across all three modules that would want tour tips?
there is an issue already for locale module (aka interface translation).

Note, the content language settings page deals both with the language module, and with the content translation (aka translation_entity) module. Same page but tips will be different when et is enabled.
multilingual.png

YesCT’s picture

Issue summary: View changes

updated remaining tasks with priority

batigolix’s picture

I toyed with creating tour tips for the block management (see attached YAML) and this led to several questions or doubts:
(I do not know if they can be addressed in this issue or if I need to create separate issues for them)

1. writing tour tips for core is not very straightforward (especially reloading the tour tips after you have edited the text, see #1944402: Tour tips not appearing when creating custom tips)

2. I include an introduction tip in the tour but it does not appear

id: blocks-management-en
label: 'Blocks management'
status: '1'
langcode: en
paths:
  - admin/structure/block
tips:
  introduction-en:
    id: introduction-en
    plugin: text
    label: 'Managing blocks'
    body: 'Blocks are the boxes of content (such as "Top stories" or "Who''s online") that can be displayed in <a href="http://drupal.org/node/171224">regions</a> (such as footer or sidebar) on your page. <a href="http://drupal.org/documentation/modules/block">Read the community documentation for the Block module</a>.'
    weight: '1'

3. What is the status of tours that cover multiple pages?

4. In empty lists you can not bind a tip to an element because the element is not available yet. For example in an empty block management list there is no Configuration link for an individual block. Can you create a tip for a not-yet-existing element?

5. Tour tips are mostly related to elements on the page. There is limited space for explanation. This can lead to redundant tips like "Click this Save button to save your changes" or "When you have finished completing the form, click ''Save'' to create the new container or save the changes to an existing container." et cetera. I think we should prevent to include very obvious tips.

vijaycs85’s picture

FileSize
23.39 KB
58.91 KB
21.15 KB
23.47 KB
31.55 KB

Hi @batigolix, quick update on #28:
#28.1 - For me, it is working, if I update the yml file in active folder and clear cache at admin/config/development/performance
#28.2 - Not sure how it works without id or class

Tried your yml file and found that the second step has id 'blocks' causing some issue because of hidden sticky table header element has same ID. Replacing it to data-class:handle solves the problem and I can complete the tour (without first introduction step).

tour-step-0.png

tour-step-1.png

tour-step-2.png

tour-step-3.png

tour-step-4.png

nick_schuch’s picture

Hi batigolix,

1) This is CMI design and as vijaycs85 mentioned above your tip items can be updated in the active store for rapid development.
2) We have an update in the following patch http://drupal.org/node/1926296 that provides the tip as a "modal" if no class or id is provided. We hope to get this committed very soon.
3) Tour coverage for multiple pages is in the following ticket: http://drupal.org/node/1942576
4) A tip can be created for a non existant element on the page. If the element does not appear it will not be shown (until present on the page).
5) I also agree that we should not try to over explain basic elements. We should focus on explaining complex and important elements.

I hope this helps batigolix.

YesCT’s picture

At some point style guide might be helpful.
Like:
User "Remember to" instead of "Don't forget to".

I wonder if we have something already... http://drupal.org/node/632280 Help text standard (for core and contrib)

jhodgdon’s picture

We have style guides for drupal.org and for user interface text. Do we need another one?
http://drupal.org/ui-standards --> sub-page http://drupal.org/node/604342 for UI text
http://drupal.org/style-guide/content

LeeHunter’s picture

I agree that we don't need a separate style guide for Tour text, but I think it might be useful to have something in the UI Patterns section, so I've started a page here:

http://drupal.org/node/2000088

Please edit as you see fit.

I'm also very keen to get some Tour content written while I'm at Drupalcon and perhaps have people work on Tours at the Docs sprint on Friday but I'm not exactly sure how to approach this. Any suggestions?

nick_schuch’s picture

Thanks LeeHunter!

I've also added a few guidelines to the UI Pattern.

For the creation of tips I think we have 2 options.

1) Take a snapshot of the interface and (using a tool like "skitch") write content with arrows directing to page element. Developer can then jump in and convert to yml files.
2) Contribute a yml file. We have documentation on the creation of these here: http://drupal.org/node/1934442. Feel free to contribute to the documentation (I will appreciate it greatly!).

Let me know if there is anything else I can do to help LeeHunter!

jhodgdon’s picture

That sounds like a great idea to do this at the Docs sprint!

A few questions/thoughts:

a) The issue summary has some thoughts on what kinds of tips/tours are wanted in core. Some of the comments starting in #19 on this issue have further discussion. The conclusions should be put onto http://drupal.org/node/2000088 if they aren't already. The main thing I think is missing are the answers to the big questions in #19, which I'm not sure have been decided or not. Lee: if you and Bojhan are both at DrupalCon, maybe you can get together and hash this out in a BOF? If the two of you can agree on what tours are wanted in Core, and some guidelines for them, I think the rest of us would probably go along with your conclusions (given that you would have considered the opinions already presented here, and be open to further discussion, etc.).

b) Is there any documentation on how to create a tour? If so, where? That would be a useful link to have on http://drupal.org/node/2000088 and that docs page should link back to http://drupal.org/node/2000088.

c) The guidelines in http://drupal.org/node/2000088 are rather vague. They don't really give me a clear idea of what a good tour would be... Questions I had: what is a "logical place" to start/stop the tour? what screens are amenable to tours? what kind of UI text does a tour need (should it be explaining how, what, where, who, and/or why?)? Since you are trying to illustrate a workflow, can a tour cover several UI pages? And can there be multiple tours for one UI page? etc.

d) Once there is documentation/agreement on *what* tours we want, *how to* documentation telling how to make tours, and clear *guidelines* on the details of the UI for a tour, then I think it would be great to do that at the docs sprint. But without all three, I think the doc sprinters would be unable to run with that project.

nick_schuch’s picture

a) There should definitely be further discussion before going into the doc sprint. I will be available if required. I also believe I can provide some clarity to #19:

1) Our goal right now (as discussed with Bojhan) is to provide tips for the Initial Experience, Blocks, Fields, Views and Multi-lingual (the links to there issues are in the summary). We should also write the tour first and then as part of the review identify things that should be fixed.

2) I don't see node edit as being a good candidate for core as the fields are dynamic. Thats not to say as a site builder I cannot build a node out and then write a tour for it. We are looking for admin forms that need a "story" told. I don't envisage us requiring a tip for every form element as items like "title" are self explanatory. The questions should be something along these lines "How do I use this admin form? How do I provide the information with the least elements?".

3) Additional information that we cannot provide in description text. We have the opportunity to "tour" the admin interface.

b) As mentioned in #34 we have the "Tour" documentation here http://drupal.org/node/1934442. It covers the creation of the tour yml files. But as I also mentioned in that comment, contributors can just provide screenshots to demonstrate a tour to be adapted into a yml file.

c) Currently tours are on a per page basis. We have this http://drupal.org/node/1942576 issue being worked on that will allow for site builders to create multipage tours to describe there site. If there is a great need for it in core tours then we have the facility to do it. My suggestion is keep it simple and describe the page the end user is currently on.

I hope this helps. Feel free to ping me on IRC if needed.

LeeHunter’s picture

I've started working on the D8 home page tour and have posted a screen capture and some thoughts here: #1920468: Write tour integration for the first page after install showing extend and other things. I thought it might be a good idea to mention it here, in case people only following the meta issue might want to add thoughts on the approach.

pmackay’s picture

I chatted with LeeHunter during the Portland docs sprint and thinking that it would make sense to have tours for other parts of core. Are there reasons why there is only a list of 5 proposed tours? What are the concerns about creating additional tours? The admin/modules page could be a useful candidate.

nick_schuch’s picture

Hi pmackay,

I strongly encourage tours being written for all part of core that require them. The "major" ones listed about are the ones the UX team have identified (definitely should be completed).

Let me know if there is anything I can do to help you in the writing of your tours.

nick_schuch

nick_schuch’s picture

Issue summary: View changes

Update related issues.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Issue summary: View changes

Updated issue summary.

Kristen Pol’s picture

Title: META: Start providing tips for other core modules. » META: Start providing tour tips for other core modules.
Issue tags: +Tour

Adding tour to title for clarity and search-ability. Adding tour tag.

clemens.tolboom’s picture

Inspired by https://drupal.org/project/config_inspector I build https://drupal.org/project/tour_builder which needs some help unfortunately :( edit works, clone not, etc

I hope this will help other then developers to write tours.

clemens.tolboom’s picture

I just tested #28 and all steps work. The tips are bouncing around on the screen.

FWIW Using https://drupal.org/project/tour_builder is useful now for discovering tours, editing tips and cloning tours. But not for adding/removing tips yet.

clemens.tolboom’s picture

I'm puzzled with how to coordinate the tour building process but will try to help out.

I just created a quick demo video on https://www.youtube.com/watch?v=f0TgQ6PRst4 (unfortunately screenflow failed me to upgrade properly.)

Kristen Pol’s picture

@clemens.tolboom !!!!! You are doing amazing awesome things! Thanks so much for stepping in and tackling making tours easy for all of us. I think having good tours in D8 will be a huge help for so many people. UX++

alexpott’s picture

I'm pretty sure that these can come after api freeze and in fact might be better if they do so they can reflect any last minute changes... since adding a tour is not an API change and is additional... it is just adding a config file.

nick_schuch’s picture

Thanks alexpott! Thats awesome news!

nick_schuch’s picture

Issue summary: View changes

Updated issue summary.

clemens.tolboom’s picture

Issue summary: View changes

Added links to related projects

clemens.tolboom’s picture

In #2027469-2: View UI Tour is not working and had a sandbox update. @aspilicious asks for tests. Which is not a bad question.

As tours reply on DOM IDs or class selectors the could not work at all if forms change or themes change rendered HTML.

It would be great to let tour module test all available tours as that would relief module developers from writing tests for 'their' tours. It would allow tour writers instead to test their tours themselves.

Is that feasible? I'm not sure how to test on wildcard paths :-/

I guess we can make it at least easier to provide a base test class.

Any ideas?

nick_schuch’s picture

Hi Clemens,

Tour module does have a tests:

http://drupalcode.org/project/drupal.git/blob/HEAD:/core/modules/tour/li...

These tests check the functionality of tour module.

Tour module does not test tour content created in other modules.

However maybe tests can be written (in this case) for Tour UI module to ensure those tips markup is present on the page.

clemens.tolboom’s picture

@nick_schuch you're missing the point or I'm not making it ;)

I've created #2028535: Provide a TourTestBase class for use by core and contrib modules. Hope that helps :)

clemens.tolboom’s picture

Issue summary: View changes

Updated issue summary.

clemens.tolboom’s picture

Issue summary: View changes

Changed link Tour UI is supposed to land in contrib: #1921188: Implement Tour UI module to the sandbox

clemens.tolboom’s picture

Issue summary: View changes

Added links to other Tour related issues.

lisarex’s picture

Issue summary: View changes

add structure and appearance

lisarex’s picture

Issue summary: View changes

add menu and content

lisarex’s picture

Issue summary: View changes

add reports and people

lisarex’s picture

Issue summary: View changes

add extend

tkoleary’s picture

Issue summary: View changes

Added an issue to the list for add/edit content

batigolix’s picture

We now have several pages on d.o. that give instructions on how to write tours:

1) https://drupal.org/node/2040099
2) https://drupal.org/node/2000088
3) https://drupal.org/documentation/modules/tour (referred to as the "official" page)

Shall we delete 1) and 2) to prevent confusion?

jhodgdon’s picture

Not really...

1) and 2) are both "standards" pages explaining the UI standards for creating tours. They belong where they are, and in my opinion, their text should NOT be duplicated (rather: it should be referenced with a link) on the other pages. (1) is the standards for what type of text to use, and (2) is the "UI pattern" standard, which tells you principles to use when designing a tour.

3) is the standard help page for the Tours module, which as I just said, shouldn't really have that section about "tours are not a standard for good UI design". Actually it shouldn't say anything about how to write tours or standards for making them.

And you forgot 4) which is the page about how to make tours (which should have links to 1 and 2 but I dont' think it does): https://drupal.org/node/1934442

https://drupal.org/node/2040099 -- This is in the user interface text standards section, so it is a page on user interface text standards for Tours, and is not about the practicalities of how to create a tour. It should have a better page title perhaps.

2)

jair’s picture

Issue tags: +Needs reroll

Needs reroll

jhodgdon’s picture

Issue tags: -Needs reroll

Um. This issue is a meta-issue and should not have a patch, so it should not need a reroll?

clemens.tolboom’s picture

I'm setting up a Tour Writers site to overcome the problem for writers to write/read patches and thus prevent needing the full monty developers setup.

For this to work (or by other means) we must allow writers to work on a single unit of a tour.

As #2028535: Provide a TourTestBase class for use by core and contrib modules is in tours needs tests which is not a Tour Writers skill and we should not require this for them. Is there a way make this work smoother?

See http://tour.drutch.nl/?tour=1 and esp. http://tour.drutch.nl/admin/config/development/tour-builder?tour=1 for my work in progress.

nick_schuch’s picture

We need test coverage for all our tours to ensure the elements remain on the page.

Tour content writers and developers can both work on the ticket in harmony. A developer could pick up the current patch and provide tests. I am more than happy to write these tests as that is where I feel comfortable.

Im not sure about http://tour.drutch.nl as I feel we need to keep the conversation here in drupal.org. If it's a sandbox for test writing we could possibly use something along the lines of simplytest.me?

clemens.tolboom’s picture

Hmmm ... simpletest.me does not have patch generation afaik. We are working hard to have these in place :) http://tour.drutch.nl is a community effort of some dutch people. Maybe it help if we state so over there :)

clemens.tolboom’s picture

The other day I talked to a trainer about our tours. From his questions I guess we are

  • building system oriented tours instead of solution oriented tours
  • basic tours as opposed to advanced tours as we have no choice to select the skill level

As I'm a coder I can only write system oriented basic tours but is that really what we need?

Reading the issue summary I do not read about these distinctions. Shouldn't we had this added to the summary?

We do have around 260 router items on /admin ... do we need a tour on most of these? Is there a selection process for what to write a tour for?

I myself will focus on the tour writer by fixing Tour UI + Tour Builder installed on http://tour.drutch.nl as that generates patches based on d.o issues which should reduce load on coders like myself. I'll try to make the writing as smooth as possible.

Bojhan’s picture

I think that we should have researched what key user journeys we wish to provide with tours, and then written tours - now we are in the whisy-washy approach of, doing whatever until people object. I'd gladly help provide that direction, but so far I have had little interaction with those writing tours.

Gábor Hojtsy’s picture

Yeah fully agreed with Bojhan.

clemens.tolboom’s picture

@Bojhan thanks for the quick reply. I agree :)

It would be nice to have some pointers for us to read about before start writing tours again.

nick_schuch’s picture

Bojhan and Gábor Hojtsy.

Completely agree. How would you feel about scheduling a hangout so we can discuss? Possibly make it a regular thing?

clemens.tolboom’s picture

Reading through the tour related issues I guess we need:

  1. A way to tour across different pages.
    1. This is probably partly covered by #2073891: Customise tour loading by URL
    2. but we can already provide links in tips like done in #2017471-3: Multilingual tour for language section and provided by #2019469: Tour module should use token for it's body (?)
    3. If we create a multipage tour we need a 'Next page' too I guess to quickly navigate.
  2. For writing proper multi-page we need I guess user skill filtering possibly done by:
    1. #1921144: Role based system for tips but is a role to decide my skill level or just what tour to see?
    2. #1924202: Tour tips are provided as configuration, so never get updated as in "I've seen these old tips so am more skilled."
    3. @sun #1809352-62: Write tour.module and add it to core mentioned a skill range from 0..100 to define the tip level.

I believe we had a condition issue regarding tours. Can we revive that issue?

(my 2 cents)

nick_schuch’s picture

1)

Multipage tour functionality has been implemented in it's simplest form. I feel that we are burning to much time on what we *might* need to implement.

Can we instead focus on what content the tour would contain, starting with single tips and then grouping from there. This will mean our tour is content driven. As this will be the first multipage tour implemented we need to make sure it's done right. We should storyboard the tour so we can determine requirements.

Im still not entirely sure we need a multipage tour but am open to the possibility.

2.

"Role based for tips" - As the issue description states, this breaks out tips to only be shown to certain roles. Those roles could be skill levels roles or content entry level roles. The code has been written and needs review (has been for 4 to 5 months).

clemens.tolboom’s picture

@nick_schuch I totally agree with our current multi page way in that it will work. Adding links per tip is fine with me.

But as @Bojhan said in #58 we need a vision which should land in the issue summary which is not reflecting our vision.

Writing tours is easy when using Tour UI but that's useless right now #2098325: Tour UI converts tip plugin from 'text' to 'text_extended'. Can we fix that?

nick_schuch’s picture

We need to organise time to discuss via a hangout. Im going to ping interested parties in the next week and get this organised.

We can look into that in the first half of the coming week. Can I ask that we don't cross post Tour UI issues in this issue queue?

nick_schuch’s picture

Issue summary: View changes

added edit user and shortcuts

vijaycs85’s picture

Issue summary: View changes

Cleaning up sub-tasks...

heather’s picture

FYI- for anyone looking for updates, there was a Tour module scrum on 6 Dec 2013, summary here: https://groups.drupal.org/node/383993

daffie’s picture

Maybe is it a good idea to fix this #2030661: Expand Tour with methods first.

batigolix’s picture

Issue summary: View changes

I moved the tech tips to https://drupal.org/developing/api/tour because they should be part of the documentation.

batigolix’s picture

I made some changes to the various Tour docs according to #51

nick_schuch’s picture

Thanks batigolix!

sun’s picture

Coming from #2040845-27: Write tour integration for People page, I'm very confused about what we're doing currently — cross-posting my comment from there over here, as this seems to be a more appropriate place for raising the concerns:

+    label: 'Managing users'
+    body: 'View and edit user accounts.'
...
+    label: 'Add a user'
+    body: 'Create a new user account.'
...
+    label: 'Search for users'
+    body: 'Find users by applying filters.'
...
+    label: 'Update accounts'
+    body: 'Select one or more users via the checkboxes to apply changes to the accounts.'
...
+    label: 'Edit user account'
+    body: 'Make changes to one user account.'

Hrm. — Do we really want to explain every possible UI interaction in tour tips?

If we do, what kind of "tip" or explanation is "Create a new user account." meant to give that wouldn't be obvious by the UI already?

I was under the assumption we introduced Tour tips to explain non-obvious things in the user interface only?

→ If we need to provide hints for the most fundamental/basic operations, then our UI/UX must be seriously flawed? (which I don't think it is)

I'm afraid, this makes little sense to me. These kind of Tour tips will only make people avoid Tour module whenever possible.

Introducing any kind of such "tips" also presents a major disrespect and discredit for the hard work of Drupal's Usability and Design teams, because the mere fact of "having to" point out the most basic user interface operations via Tour tips would mean that the entire user interface design is a utter #FAIL.

Or to put that in reverse, because it might not be obvious:

The user interface design is solely responsible for making obvious things obvious. User interface design enables end-users to use Drupal intuitively. A well-designed user interface needs absolutely zero explanation; every human immediately understands how to use it. That is the one and only goal of user interface design.

This patch (and likely others) introduces tips for the most obvious operations in the user interface. These operations should not need any kind of explanation in the first place. IF they do, then the solution is NOT to explain to the user how to use the interface. — The only acceptable solution is to fix the user interface design.

In short, if there is a problem with any of these basic operations, then we need to fix the UI. Tour tips should be reserved for non-obvious interactions.

A non-obvious interaction would be to point out that it is possible to add fields to users. Or to add view modes. Or that you can change the administrative user listing/view to customize it to your needs. Or that you can leverage the "Reset password" functionality to temporarily grant someone else access to a user account with a one-time login link without sharing the password. — All of that is not obvious, and cannot be solved by user interface design.

@Bojhan et al: I'm surprised that these concerns were not raised by the Usability team? — Did these aspects slip through the cracks? Or did you actually raise the same concerns already but they were dismissed/ignored...?

jhodgdon’s picture

+1 for #72. Really. We should not need to point out the obvious, and I think the UI in general is fairly obvious.

One thing that is not obvious to people, which consistently comes out in the usability studies, is how to tell the difference between Structure and Configuration, and things like that. Tour is not going to help in that regard, however, because it (as far as I know) doesn't give you a way to discover how to accomplish a task, it's just giving you pointers to what's on a UI page you've already located (right?).

That said, there is probably a use for Tours in a few places. For instance, explaining what the Views UI does when you're setting up or editing a view. Views are intrinsically complicated beasts, and the UI is accordingly complicated -- I think a Tour could help people figure out what's going on.

So, really, yes maybe time to step back and figure out where tours actually make sense before attempting to create them on every page? I didn't realize that was the plan... seems like a lot of unnecessary work?

clemens.tolboom’s picture

In #57 - #65 the same issue popped-up where @Bojhan answered the UX part @sun asked in #72

sun’s picture

Sorry, somehow I missed those comments (despite just 75 comments, this meta is quite lengthy…)

It seems we all agree with each other that the current direction is not what we want? Do we want to postpone all of the sub-issues to prevent further work on them until we have a better plan?

Would it make sense to create a new "policy" issue to discuss what exact tour content we want to have? (summarizing existing comments here in its issue summary) Anyone up for doing that? :-)

larowlan’s picture

Will Work On An Example Today, With Summary
Great To See An Answer To The Question, 'so How Are We Going To Use This Awesome TooL', finally

nick_schuch’s picture

I completely agree with @sun and @jhodgdon on this.

I also want to point out that for quite some time we have been trying to build a plan of attack and haven't had much support or buy in from the community. It got to the point where we just needed to start writing tips to get movement. That said I understand that there have been much more pressing issues.

After discussions with @larowlan yesterday we feel that we can tackle this differently.

These are the changes that we have been disucssing:
* Changing the "tour" toggle to be "tours" and consistent across all pages. When clicked the end user will get a list of tour's that they can follow.
* Tour's issue's will change from a "per page" and "per scenario". I would like the UX team to provide a list of scenarios that we can then tackle in individual issues.
** @larowlan is also working on a tour for content management to demo this.

larowlan’s picture

FileSize
14.25 KB

So here's a patch and screencast demonstrating the proposed approach at #77

So if we decide this is the good approach the battle plan would be:
* split the api changing/addition elements of this patch into a new issue add UnitTests for TourManager and get that committed
* build a list of key 'concepts' surrounding working with Drupal and open new issues for each of those
* refactor/close the existing issues that don't fit this list of concepts.

Thoughts?

aspilicious’s picture

I'm afraid the horizontal bar will be to small for every possible tour (core + contrib)

larowlan’s picture

Yes I agree, what does shortcut do in that situation?
Also, this patch adds per-tour permissions, so user/1 would see them all but other users might get a sub-set

aspilicious’s picture

Shortcut isn't made for more then x shortcuts than it starts to look strange :)

Bojhan’s picture

@sun We did not review most or all of the tours. I tried, but its frankly too much of a hassle and frankly I don't think it gets much review from those who commit it either. I completely agree with all your assumptions on explaining broken UI's

batigolix’s picture

I publish this issue again.
Was there a reason to unpublish it?

Bojhan’s picture

I'd like to clarify that the best way to move this forward is to establish principles to which all tours should follow. @sun I did try to pursue that strategy, but we kinda got steamrolled by all the tours that get committed.

batigolix’s picture

According to this comment there has already been some discussion on what kind of tours should be included
https://drupal.org/comment/7192088#comment-7192088

Some Tour principles / guidelines have already been documented:
https://drupal.org/node/2000088
https://drupal.org/node/2040099

larowlan’s picture

but we kinda got steamrolled by all the tours that get committed

FYI there is only one tour in core, and that went in with the module.

larowlan’s picture

So do we agree that #78 is the way to go?
If so do we agree that the list of tours at #26 is what we should be shooting for?
That then leaves handling tour overflow when there are too many to display in one row.

batigolix’s picture

I'm OK with #26 and #78

Bojhan’s picture

Actually no, I don't think that this is a good idea. We shouldn't populate the left side with even more stuff (also how does this scale on the horizontal version?). We shouldn't have more than one tour per page, why are we having conflicts?

nick_schuch’s picture

As an alternative why don't we keep the "Tour" button in place and also provide a list of tour on the help modules listing page? That way we still have the ability for discovery and playing a tour on the current users page.

clemens.tolboom’s picture

Added links mentioned by @batigolix in #85

batigolix’s picture

FileSize
97.01 KB
63.79 KB

Attached 2 screenshots to visualise Nick's idea from #90

Something along these lines was already discussed before (comment #19 in [#7902453])

Bojhan’s picture

Good idea, I would put it below the topic table though. Since its likely this will grow.

jhodgdon’s picture

I don't think removing the suggestions for how to set up your web site from the main Help page is a great idea, myself. Some people do well with text-based instructions; others will do better with Tours.

Adding the Tours to that page does seem like a good idea, though. I like the explanation of what Tours are; maybe we should improve the explanation of the help topics too, to explain that they are per-module and give an overview of the module's functionality?

As a note, there is also an issue open about redoing how the main help page is rendered (it doesn't change what is displayed, just the rendering/theming):
#1986164: Improve the way main help page is rendered

larowlan’s picture

Embedding those images

larowlan’s picture

So I think we're in consensus as follows:
* Tour implements a block providing a list of tours, this can reuse some of the code in #78
* Said block is added to the main help page, in addition to the existing content, standard install profile will handle placing this block (ie create core/profiles/standard/config/block.block.tours-help.yml to place it)
* Tours remain per page and the button only shows when there is a tour on a given page.
* Tours focus on concepts instead of describing the UI. Priority concepts are as listed at #26

Any objections? Speak now or forever hold your peace etc. :)

jhodgdon’s picture

I'm confused. The images imply you want to remove the help text and replace it with tours list, but the proposal in #96 does not agree.

nick_schuch’s picture

jhodgdon,

larowlan embedded the images from #92 so others didn't have to click on them. larowlan hasn't listed the "remove the help text" in the latest proposal because of your suggestsions in #94.

I don't think removing the suggestions for how to set up your web site from the main Help page is a great idea, myself. Some people do well with text-based instructions; others will do better with Tours.

So instead we are just going to add the list of tour's after the help content on the page.

Also,

Adding the Tours to that page does seem like a good idea, though. I like the explanation of what Tours are; maybe we should improve the explanation of the help topics too, to explain that they are per-module and give an overview of the module's functionality?

I believe we were referencing a list of tour's with links. Similiar to list of hook_help pages. That way end users can discover the tours.

larowlan’s picture

Yeah, I'm not saying remove that body of text, I agree with @jhodgdon - I just embedded the images so other could see them easily.
I'm saying add the list of tours to that page (when tour is enabled, using a block).

jhodgdon’s picture

Thanks for the clarification.

So one possible action item to add to #96 would be to improve the text just under the Help Topics header, so that it is clearer about saying what those links are, which is descriptions of each module's functionality (to distinguish between those links and Tours).

Other than that, I think it's a good plan. +1.

batigolix’s picture

Screenshot to visualize what this should look like (includes proposals / suggestions #96 - #100 ).

proposed help page w tours

jhodgdon’s picture

#101 looks good to me! +1! First line under Help Topics should be "Each help topic..." not "topics". Other than that, and maybe less flowery wording under Tours, looks good.

batigolix’s picture

I created a separate issue for the necessary changes in the main help page:

#2205713: Adapt main Help page (admin/help) so that Available Tours block can be added

batigolix’s picture

batigolix’s picture

And here is a separate issue for creating the block:

#2205801: Create Available Tours block

YesCT’s picture

Issue summary: View changes

Asked also in #2350615-77: [policy, no patch] What changes can be accepted during the Drupal 8 beta phase? for confirmation.
updated the allowed in beta info in the issue summary.

This maybe should be a major though, with each child a normal?

jhodgdon’s picture

I agree with what alexpott said on the "beta policy" issue: Tours are documentation, so they are an allowed change. Let's proceed!

nick_schuch’s picture

Woohoo! Awesome news!

webchick’s picture

Coming here from #2040845: Write tour integration for People page. Here, we have a new contributor who's adding a tour to the admin/people page. (Cos, you know, that's what the issue says to do. :))

I am hesitating though, because a) this page is "just" a view, and is therefore conceptually identical to admin/content, admin/comment, admin/file, etc. so committing this as a one-off would create an inconsistency b) the help text in quite a few places more or less says back exactly what the button labels are in slightly different words, which doesn't seem overly helpful.

I think before moving on more of these Tour issues we need to come to consensus on:

1) What interactions do we put Tours on? To me, I would make some kind of a guideline like "If something spans multiple pages, use a Tour." Adding a user isn't really one of them. But, a Tour explaining how to create users, manage their roles, and assign permissions (for example) definitely would be.

2) What level of granularity do we want to go for in Tours? Do we literally want to outline every step, even if they are pretty obvious? Or do we only want to highlight the major steps that people might have questions about or accidentally skip?

3) Probably other things. :P You should try to have at least 3 things in a list. ;)

IMO, we should postpone work on the rest of the Tour issues until we agree on a standard.

webchick’s picture

OK, think I've managed to postpone all the sub-issues now.

jhodgdon’s picture

Guidelines++

However, in practice I think the suggestion in #109 item 1 will not work. For one thing, I do not think that Tours actually can span multiple pages.

Also, I don't think tours are a great place for conceptual stuff, like explaining philosophy of how to manage users and set up roles in a sensible way. That should probably be in user_help(). Whether it *is* in User Help actually or not, I don't know, but it seems like a good thing to go into a Help document rather than a Tour.

So let's think about this a bit. Tours are a mechanism for guiding someone through several steps or explaining a UI, right? Ideally, our UI should be clear enough that a tour isn't necessary on most pages... I mean, the Usability folks are always making us remove UI help text (field descriptions) in favor of having clear field names on forms and easy-to-use UI.

So, really, what is the purpose of tours? Do the tours we already have make sense? Should they be pared down?

I don't have an answer... really am not sure what the purpose is, or where we really need them. Do we need to do some more usability research and only add tours to pages people don't really understand?

Bojhan’s picture

I am not sure if we actually need to do more research here. They have been part of testing ever since they were introduced, but one of the main problems is the lack of strategy.

From my point of view tours serve a very clear purpose:
1) On-board users into very complex concepts and UI's.
2) Our exit-strategy for poor UX in many of our interfaces.

However it should not be a "apply it on any page" - which for a larger part seems to have been the current strategy. I wholeheartedly agree with jhodgdon that we shouldn't try to capture philosophy. Tours only purpose is to provide a very quick introduction, so you can find and understand your way around key concepts in an interface.

Frankly if our standard views like the content listing need a tour, we are really not performing well.

Kristen Pol has been involved with many of these issues, so I'd love her insights.

clemens.tolboom’s picture

We are repeating ourselfs. See eg ~ #57 - #75 (and probably more) aka lack of vision what should and should not need a tour and how. Guess someone needs to step up (again) to fix this.

Note we have more meta-ish pages like

- #1940590: META: Write a multipage multilingual tour
- #1945414: META: Tour module

vijaycs85’s picture

a) this page is "just" a view, and is therefore conceptually identical to admin/content, admin/comment, admin/file, etc. so committing this as a one-off would create an inconsistency

It would make lots of sense to have help on all those pages, if the help text is specific to the content or context of the content page. Also we are not annoying new users with auto popup-ing tour. 'Get help, if you need it' doesn't harm. I would prefer to be available all admin pages to make it consistent. So the guideline/instruction to new user would be 'just click the tour icon on the page to know about the interface'.

b) the help text in quite a few places more or less says back exactly what the button labels are in slightly different words, which doesn't seem overly helpful.

I agree and IMHO, this is because of may be the people who knows the system writing the help text? So may be we should

1. It would be nice to get non-drupal/content authors without any technical knowledge to describe what is hard and what would be helpful.

2. Check few other systems and come up with our own list of items.

larowlan’s picture

We can do multipage tours.
Appending ?tour=1 to the end of a link will auto-start a tour, so tour A can link to next page to continue the tour.

The patch above made some work on a list of concepts - comments at #90 by Nick and screenshot of the concept by @batigolix at #92 are still the best approach in my books.

Gábor Hojtsy’s picture

@larowlan: how do you specify which tour on that page to take the first step of? As far as I have seen before there can only be one tour on a page. Did that change? That sounds like limits the possible use of multipage tours a great deal.

jhodgdon’s picture

So... Then here are some, I think, non controversial policies:

1. We should have a tour only to explain things that aren't obvious. A tour shouldn't be telling people things that they can easily figure out from the UI (like repeating the UI text, or just rewording it slightly).

2. A tour should be a quick intro that explains how to use the UI to accomplish a task, possibly over several pages -- not a method for giving the philosophy behind the task.

3. Not every page necessarily needs a tour.

So. Assuming we can agree on those three policies for what a tour should be, I think we need to:

a) Go through our existing tours and decide whether we need them, and if we do, whether we can make them shorter by removing some of the tips in the tours. I'm not even sure what tours we currently have... can someone make a list?

b) Go through the list of proposed tours and decide whether we really need them. Bojhan: do we have any Usability research to suggest which of our UIs, even with the work we've done in D8, are still confusing? Everyone: Are there particular UIs that you think are particularly complicated or intimidating, where you think a tour would be beneficial?

Regarding (b), the Edit View page comes to mind -- there are relationships, fields, filters, contextual filters, oh my! So I think that this page should have a tour (and I think we may already have one). But I wouldn't think we would need one on an individual Configure Field page for Views, or an Add/Edit Menu Item page in Menu UI, etc.

[Thanks @larowlan for clearing up my misconception about multipage tours, by the way! And Gabor there can currently only be one tour on any one page, I believe.]

Gábor Hojtsy’s picture

Existing tours:

core/modules/language/config/install/tour.tour.language.yml
core/modules/language/config/install/tour.tour.language-add.yml
core/modules/language/config/install/tour.tour.language-edit.yml
core/modules/locale/config/install/tour.tour.locale.yml
core/modules/views_ui/config/install/tour.tour.views-ui.yml
----
core/modules/tour/tests/tour_test/config/install/tour.tour.tour-test.yml
core/modules/tour/tests/tour_test/config/install/language/it/tour.tour.tour-test.yml
core/modules/tour/tests/tour_test/config/install/tour.tour.tour-test-2.yml
larowlan’s picture

You can have more than one tour on a page but they are combined and shown together, with tips ordered based on weight. You can alter weights using the alter hook.
If you want to do a multi-page tour and filter the tips on the second page to a specific tour, you can make use of the class attribute of each tip and make your url /some/path/with/two/tours?tour=1&tips=some-class - that will autostart the tour and only show tips with a class of some-class.

rodrigoaguilera’s picture

Category: Task » Plan

Now we can make this a plan #1815826: Add "Plan" category to categorize what is called "meta issues" in core right now

Tour de drupal without many tours in core will be sad ;)

jhodgdon’s picture

That may be, but we also do not want to have Tours in Core just because we can. We need to be a bit more strategic and make sure that (a) they follow our UI guidelines and (b) they actually are needed.

See #117 for proposed guidelines and next To Dos. So far no one has commented on this proposal, or offered to move it forward.

jhodgdon’s picture

We should revive this.

Right now there are only a few tours in Core and we haven't decided whether (a) those ones make strategic sense and (b) we need additional ones.

The existing tours are (from the core directory, omitting tests):

./modules/locale/config/optional/tour.tour.locale.yml
./modules/views_ui/config/optional/tour.tour.views-ui.yml
./modules/language/config/optional/tour.tour.language-edit.yml
./modules/language/config/optional/tour.tour.language-add.yml
./modules/language/config/optional/tour.tour.language.yml

So... What tours do we really need, and why?

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

jhodgdon’s picture

We still need to restart this issue.

What we need to do:

a) Decide on at least a few Tours that we need to have in Core.

b) Decide on some guidelines for what they should say and what they shouldn't, and how they should say it. For comparison (or a starting point), we have these guidelines for the User Guide project:
https://userguide_new-drupal.dev.devdrupal.org/guidelines/good-writing.html
(and following pages -- and for access use "drupal" as the user name and password on that site!)

c) Write up instructions for how to make a tour (if they don't already exist somewhere on Drupal.org -- is there a UI module to use?).

d) Un-postpone or create appropriate child issues, and do them.

For (a) what comes to mind as absolute essentials would be something like:
- Placing a block (possibly including making a custom block?)
- Adding a field to a content entity (such as a Node content item) -- is it possible to reuse that Tour for all of the field add processes, like for custom blocks or users or whatever?
- Something multilingual?

Gábor Hojtsy’s picture

Re something multilingual, 3 out of the 4 tours in core are already for multilingual :) However, open to more ideas of course.

jhodgdon’s picture

True! I realized that after I made that post. Anyway, we definitely need to think strategically, about what tasks users need to learn how to do, that aren't obvious.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

xjm’s picture

Status: Needs work » Active
Issue tags: -Tour +Needs usability review

Looking at #2069073: Allow Tours to be taken by users that cannot access the Toolbar (e.g. anonymous users) made me remember that Tour existed and I was surprised to see that we still only have the tours that were added for multilingual and views before release. I'd like to propose that we not postpone adding tours like this, for a couple reasons:

  1. Yes, it's better to fix interactions so that they're intuitive rather than having to provide documentation for them. However, it's easier to add a tour for an existing UI than to add a new UI. That doesn't mean we won't also add a new UI later.
  2. We require a hook_help() page for every single module and handbook pages off on Drupal.org for new modules as part of the documentation gate. A tour is a more useful form of documentation than either of these, because it's contextual.
  3. While I can see how adding more information to a page could make the UX worse rather than better (the same as adding unneeded descriptions to form elements), the Tour module is not very in-your-face about provided tours, so it's not actually that bad if we add a tour that's not ideal.
  4. Blocking this has made this initiative stall out and the usefulness of this great module is limited when almost nothing provides tours, because it's not very discoverable when so few things have tours. If we had more tours, it would be easier to find things that do have tours.

Some obvious candidates for tours:

  • Each tab of the Field UI (and explanation of the tabs themselves).
  • The Extend page.
  • The Block UI (although the work on Layouts might eventually deprecate this page).
  • The Workflow UI.
  • The Appearance page.

So rather than blocking everything on defining best practices for something we don't have a lot of examples for, let's start adding examples and making iterative improvements. We can submit each proposed Tour for usability review during the patch review process, which I think will be more effective than trying to define an overarching policy.

Tagging for usability review for this suggestion. :)

xjm’s picture

Issue summary: View changes
Wim Leers’s picture

❤️ #130!

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

jhodgdon’s picture

I just came back to this issue after a long absence. I think we can probably recruit docs people to help create tours, if we (a) write up some instructions on how to create them (b) review the guidelines for tours (there are some linked in the summary) and make sure they're clear and (c) decide which tours to create.

The suggestions in #130 sound good to me... I just posted on https://groups.drupal.org/node/518325 to get some more voices into this discussion about which tours we should make, but if no one objects, maybe we should just start with xjm's suggestions? Meanwhile in the next few days I'll start looking through the guidelines and docs and make sure we have a clear process for non-programmers to contribute by creating tours (which should be possible given https://www.drupal.org/project/tour_ui ).

Thoughts?

hansfn’s picture

Issue summary: View changes
jhodgdon’s picture

I looked through the issue summary and found a ton of links... many of which ended up in the same place. In the end I had one module page and 3 documentation pages that looked useful, and still not really a "Beginners guide to making a tour" that could be used easily by non-programmers.

So, I created a preliminary page with instructions on how to create a tour using the Tour UI module: https://www.drupal.org/contributor-tasks/create-tour

However, in going through the steps, it didn't work for me. I created a fake tour for the Appearance page (route: system.themes.page) of the System module, but after creating it using Tour UI, and clearing the cache, the tour button doesn't appear. Is there something I'm missing that I would need to do to make a tour appear for this page? If I go to the Languages page, I do get the "Tour" button, so I know Tour is working in general, but it isn't displaying the new tour I created in the UI.

tim.plunkett’s picture

I haven't used Tour UI lately. But if you write them out by hand, you'd need to fully reinstall the module providing it.

jhodgdon’s picture

Hm. That's odd. You'd think either clearing the cache or maybe deleting/importing would work... I'll try some things and report back.

jhodgdon’s picture

Issue summary: View changes

Actually, it works without a cache clear. I had a typo in my route that today I can clearly see, after a few days. Doh!

So, I'm adding https://www.drupal.org/contributor-tasks/create-tour to the issue summary and reorganizing the issue summary and removing duplicate links.

I think there is enough here that if we decide on tours that need to be created, and create/un-postpone a few issues, we can let some non-programmers loose on actually creating the tours. I'm assuming that if someone uploads a text file that's an exported tour, we can find someone to convert it into a patch. :)

jhodgdon’s picture

Issue summary: View changes

Removing some duplicate lines in the issue summary (in list of tours to possibly create).

jhodgdon’s picture

Issue summary: View changes

We discussed this issue in the weekly usability meeting yesterday, which was recorded if anyone is interested -- Tours were the first topic of discussion:
https://www.youtube.com/watch?v=BechK49LvY4

My summary of the discussion:
a) No one is sure whether Tours are actually beneficial. Questions that would be great to answer via usability testing:

1. If there is a tour on a page, and a user is confused about using the page, do they find and click on the Tour button? [Note: there is also a Help button, up in the toolbar near the Tour button, with the same ? icon as the Tour button; that button takes you to admin/help. We also aren't sure if the word "Tour" conveys "Help in how to use this page"]

2. If the user does click on the Tour button, is the information they get from the tour actually helpful?

b) One problem with trying to answer these questions via usability testing is that there are currently only a very small number of tours in Core, so the Tour button isn't present on most pages, making this difficult to test.

c) No one at the meeting had any suggestions for standards about how to create tours, what should be in them, etc.

d) @yoroy has previously written a blog post about the conceptual disconnect new Drupal users feel:
http://yoroy.com/pieces/drupal-ux-conceptual-criticals
These points would be good places to look for where we should have tours and/or help topics.

e) Besides Tour, there is also the Help block that can be put at the top of admin pages by implementing hook_help() [and ensuring the Help block is placed there, which it is in the standard profile]. This is a good place to put an overview of the admin page, and doesn't require clicking to get to the tour.

I'll add this information to the issue summary...

clemens.tolboom’s picture

http://drupal.d8/admin/help list Tours belonging to enabled modules.

I've updated https://www.drupal.org/project/issues/tour_builder to have a UI for exporting tours.

https://www.drupal.org/project/tour_ui has 350 installs. So guess it is used somehow.

Tour UI + Tour Builder actions

jhodgdon’s picture

How is tour_builder module different from tour_ui? Hm... I looked at the module page for tour_builder and it looks like it extends tour_ui, but I'm not sure exactly how? I'm wondering because I wrote a step-by-step guide to how to create a tour, and I didn't use Tour Builder.

Also, you can already export a tour by using the Configuration Manager module (which is in Core)...

clemens.tolboom’s picture

Tour UI was build for Tour (core) doing help with CRUD.

Tour Builder was my try to help non coders applying/creating patches (currently (again) broken) supporting the 'editor' workflow.

To remove a developer out I just started on Tour UI #2955523: Add route names for easier adding Tours.

Tour UI has still #2098325: Tour UI converts tip plugin from 'text' to 'text_extended' which I tempt to solve through Tour Builder which will an ugly string-replace.

Electric Doorknob’s picture

During a mentored sprint in Nashville several new contributors developed and submitted patches with basic starts of tours for several core modules noted in this issue.

Most of our patches have failed testing by the CI bot due to schema validation problems similar to the following:

Drupal\Tests\settings_tray\FunctionalJavascript\ConfigAccessTest::testBlockConfigAccess
Drupal\Core\Config\Schema\SchemaIncompleteException: No schema for tour.tour.menu-ui

I developed the patch in #2040823: Add tour integration for Menu admin page, while others developed patches for #2044407: Write tour integration for shortcuts page, #2044399: Write tour integration for user edit page, and #2040375: Write tour integration for Appearance pages, which also fail the same schema related tests.

We're all apparently making the same error, but I can't determine what it is based on the documentation for developing Tours here: https://www.drupal.org/docs/8/api/tour-api/overview , nor by comparing new work to the existing tour configuration in views-ui.

Any tips? Thanks!

jhodgdon’s picture

I believe the problem is that the tours need to be placed in config/optional, not config/install.

The reason is that, for example, if you're making a tour for the Menu UI module, the Tour module is not a dependency of that module, so some tests for Menu UI do not have the Tour module enabled. Therefore, the tour config schema is not defined when that test runs, leading to a problem of "I don't know what the schema of this tour.tour.menu_ui thing I found in config/install that I'm supposed to install".

So, moving the tour from config/install to config/optional (which is where you place config that has a module dependency that isn't a dependency of the module where you're placing the config) should fix it. For example, if module A doesn't depend on the Views module, but provides a view that will be there if the site also has the Views module installed, you'd put that in config/optional as well.

Hope that makes sense... thanks for contributing!

jhodgdon’s picture

Issue summary: View changes

I just updated the docs page https://www.drupal.org/contributor-tasks/create-tour with this information (put it in config/optional). I'm also going to highlight this page in the issue summary, as I think it has the most complete instructions for how to create tours for new contributors.

Electric Doorknob’s picture

It makes perfect sense, thanks for the explanation! Off to re-roll patches...

andrewmacpherson’s picture

Assigned: nick_schuch » Unassigned

Nice to see some progress with some of the child issues. Around half a dozen have recent patches for review.

I don't know if tour module got much accessibility review before D8 was launched. The recent tour-writing activity prompted me to look into it, and I've started a plan at #2961001: Improve accessibility of tour module.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.6 was released on August 1, 2018 and is the final bugfix release for the Drupal 8.5.x series. Drupal 8.5.x will not receive any further development aside from security fixes. Sites should prepare to update to 8.6.0 on September 5, 2018. (Drupal 8.6.0-rc1 is available for testing.)

Bug reports should be targeted against the 8.6.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

clemens.tolboom’s picture

I'm working hard to make Tour UI a stable release so testing core tours as a side effect.

Reading the comments above I guess we can un-postponed all postponed Tour writing issues?

I found 9 after normalising some titles:

- 9/14 'Write tour integration for ...' https://www.drupal.org/project/issues/drupal?text=Write+tour+integration
- 4+1 meta / 5 'Multilingual tour for ...' https://www.drupal.org/project/issues/drupal?text=Multilingual+tour+for
- more?

Is there a better way to find Tours? [edit]Yes through related issue[/edit]. I would prefer as component the tour module; guess people want to do something with Tours.

clemens.tolboom’s picture

Version: 8.6.x-dev » 8.8.x-dev

Drupal 8.6.x will not receive any further development aside from security fixes. Bug reports should be targeted against the 8.8.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.9.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.7 was released on June 3, 2020 and is the final full bugfix release for the Drupal 8.8.x series. Drupal 8.8.x will not receive any further development aside from security fixes. Sites should prepare to update to Drupal 8.9.0 or Drupal 9.0.0 for ongoing support.

Bug reports should be targeted against the 8.9.x-dev branch from now on, and new development or disruptive changes should be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.2.x-dev

Drupal 8 is end-of-life as of November 17, 2021. There will not be further changes made to Drupal 8. Bugfixes are now made to the 9.3.x and higher branches only. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.15 was released on June 1st, 2022 and is the final full bugfix release for the Drupal 9.3.x series. Drupal 9.3.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.4.x-dev branch from now on, and new development or disruptive changes should be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.9 was released on December 7, 2022 and is the final full bugfix release for the Drupal 9.4.x series. Drupal 9.4.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.5.x-dev branch from now on, and new development or disruptive changes should be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

quietone’s picture

Status: Active » Postponed

This extension is being deprecated, see #3336033: [Meta] Tasks to deprecate Tour module. It will be removed from core and moved to a contrib project, #3376099: [11.x] [Meta] Tasks to remove Tour.

This is now Postponed. The status is set according to two policies. The Remove a core extension and move it to a contributed project and the Extensions approved for removal policies.

Version: 9.5.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.