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

Problem/Motivation

Now that we have tour.module in core we want our other core modules to benefit.

Beta phase evaluation

Reference: https://www.drupal.org/core/beta-changes
Issue category Task because it is not a bug, the feature that allowed tours is already committed, so this is a task to add tours. per https://www.drupal.org/core/issue-category
Issue priority (might be) Major because important per community consensus, and this meta represents adding tours across many systems. per https://www.drupal.org/core/issue-priority
Unfrozen changes Unfrozen because children only(?) change add tour configuration (in yml), maybe a tour test, and css changes (maybe adding some css selectors to code for the css to work)
Disruption Not disruptive for core/contributed and custom modules/themes because it will not require a BC break/deprecation/internal refactoring/widespread changes. Children should be adding things, not changing them.

So this meta, and its children should be allowed during the beta.
And up until string freeze.

Proposed resolution

Start discussions (create tasks) per core module and start committing new tips where necessary.

Remaining tasks

Make sure you've read Patterns for tours and Tour text standards.

  1. Initial Experience #1920468: Write a tour for the first page after install showing extend and other things
  2. Blocks #1926294: Write tour integration for block_content.module
  3. Fields #1960824: 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: Tour for admin/content
  9. Add/edit content #2044397: Write tour integration to add/edit content UI
  10. Menu #2040823: Write 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

Completed tasks

Priority from #26
0. Discuss here general guidelines, add to the list of pointers in this issue summary

  1. Views - some done in #1809352: Write tour.module and add it to core (needs an issue to finish/polish the views part)
  2. Structure #2040791: Write tour integration for Structure page
  3. Add/edit content #2044397: Write tour integration to add/edit content UI

others:

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

Candidates for tips

Pointers

Related projects and issues

Existing documentation

Technical pointers when creating tour tips

Technical pointers when creating tour tips

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

StatusFileSize
new4.33 KB
PASSED: [[SimpleTest]]: [MySQL] 52,247 pass(es).
[ View ]
new422 bytes
new49.25 KB

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 a tour 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

StatusFileSize
new76.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

StatusFileSize
new23.39 KB
new58.91 KB
new21.15 KB
new23.47 KB
new31.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.pngtour-step-2.pngtour-step-3.pngtour-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 a tour 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: Provide a method for end users to be notified on new/update tips. 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

StatusFileSize
new14.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

StatusFileSize
new97.01 KB
new63.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!