Implement cross-reference links that refer to logically closely related functions.

Interesting and sounds like the 'eventlog' idea chx had when watching Drippy during Drupalcon. Subscribe for now.

I like this idea. subscribing

Cleaning up my queue and changing my position on this:

We've worked hard to remove help texts from D7 and put effort into improving workflows that should reduce the need for 'did you know' style help. And even if there's a good use case, I don't imagine that to be a core thing.

Or maybe not? :) Coming from #1164760: [meta] New users universally did NOT understand that you can extend Drupal

subscribing.

I'm opposed to this... If the user interface needs more than one sentence of documentation, then it needs to be re-thought. Let's fix the UI first before adding a bunch of inline documentation that noone will read.

-1

I coded up a preliminary but useful version.

It presents as a block that appears in the help region, for administrators on non-admin pages. As it is, the only way to turn it off is to disable the module, which is instructive in and of itself. It shows random helpful 'knowables,' and is hard-coded to link to a path on drupal.org.

Needs a test. Also: Contextual menu/link that takes the user to a page with an explanation of how to turn the thing off. Perhaps something like hook_knowable_info(). And... Looking over the code now I realize I used t() instead of st() for the knowables file loaded by hook_install().

From the include:

What is a 'knowable?' A knowable is a short statement that introduces a user to a topic in a general way.

The main text should be two sentences or less. The first sentence is a broad statement regarding the topic. The second sentence explains how to achieve the topic goal.

Following these two sentences is a link to a page on drupal.org which presents a more in-depth discussion of the issue. This link has two components: The link target, as a relative path to drupal.org, and the text that is linked.

Example: "Drupal can be extended with modules and themes. These can be downloaded from drupal.org, and endabled on the Modules administration
page."

Link: How to install modules and themes. (This links to documentation/install/modules-themes/)

Or... consult this handy picture.

Maybe this belongs as a sandbox project now?

I've been thinking for a while that this is something missing in Drupal that a lot of complex software projects include: the helpful tips that pop up (and can be disabled by cocky users who think they already know it all ;-) ). But of course it should have been in core in D7 and should be in core in D8 if we want people who are new to Drupal to more easily get over the notorious "learning curve".

Like bfroehle, I'd suggest sticking this in a sandbox project. My thoughts on this still apply at #6 though.

-1
I hate tips on all softwares that have them.

If you look at the comments in the 'knowables' file, you'll see that the rules are: No more than two sentences and always link back to drupal.org.

And again, this is a response to #1164760: [meta] New users universally did NOT understand that you can extend Drupal.

Sandbox here: http://drupal.org/sandbox/Mile23/1296446

subscribe

How would you make it so that if you were a new user of Drupal, you WOULDN'T hate the tips? And is it so bad if many new users would find it useful (and you just have to click once to turn it off ... or perhaps turning on/off the "tips" could be part of the install setup and you can choose to leave it off when you install, but others with less experience would want to leave it on? i.e. a setting to "install Drupal with additional features to help new users")

@Rob Loach: A sandbox project or even a contrib module to add this (i.e. NOT in core and NOT installed by a simple default setup option) would defeat the WHOLE purpose if the issue we are targeting is that new users don't even understand that Drupal has a library of contributed modules to extend it. ;-)

Of course not everyone would like it, but a few pointers can go a long way when learning your way around software with a learning curve as steep as Drupal's.

True. I was thinking again about this, and trying to get in the shoes of a complete newbie:

Tips could save hours of digging for novice users, even though it is irritating for some.
Taxonomy, Fields, Entities and other complex concepts (for newbies) could be learned just by using them with the help of the tips rather than having to look into a full documentation over d.o.

We could solve this with an option to turn it off on the install process (but tips should be shown by default). And when installing from drush, tips could be off by default (although this would be a drush issue).

We could also have more than 1 tip for a page, and they would rotate. A button for "next" and "previous tip" would be cool, too...

I think part of the hatred of tips comes from two things:

1) The vagueness of the terms 'tips.' In my example, 'tips' are actually 'knowables' which is also pretty vague as a term.

2) Encounters with crappy tip systems in the past. Clippy and BOB come to mind... "Hi! I'm Clippy and now I'm on your screen apropos of nothing!"

The idea of having tips is a good one, but the success of it depends entirely on the content, not the fact that there's a tip section.

For Drupal core, this means a few things: Someone has to own the project and exert discipline. Also, the system shouldn't be extensible (meaning: it should only be for Drupal and not for contrib, in order to maintain editorial scope).

So really, the request here is not simply for a tips system for new people, but for a QA infrastructure. Coding a module to do it is no sweat, but making sure the content is good is the real concern.

Good points Mile23. I reopened this as a possible approach towards helping people connect the dots. Testing showed people do not find out easily that Drupal can be extended. Content types are hard to find. Show/hide logo setting is miles away from setting site name. Some things can be improved by further changes to the admin info architecture. For other things we might want to suggest 'places to go'. We've already seen that adding such links to the help texts at the top of the page doesn't really work.

For example, where on the 'create content' page do we put the suggestion 'create your own content types'?

For example, where on the 'create content' page do we put the suggestion 'create your own content types'?

That's simple. Append an additional content-type choice that says something like "New content-type / Add a custom content-type to the above list." and link it to admin/structure/types/add.

Right, and now for the generalized solution :)

I'd prefer a targeted solution. When I'm on the "Add content" page, I don't want to see a generalized help tip selected at random, but a link to the "Add content type" page would be nice.

Lets try and come up with a couple of key scenarios where a little hint/link would be helpful

Hi yoroy, it's been a while since this thread was active, but I saw you posted this "mock-up" of the "tips" in #1164760: [meta] New users universally did NOT understand that you can extend Drupal

http://drupal.org/comment/reply/1164760#comment-6448460

I like those. :-) Of course they should be activated by a core module (ideally) that is enabled, by default (for newbies installing Drupal), but can be turned off (for those annoyed by the “tips”.

I think that tips would be great for newbies but at the same time might be annoying to long-time users. So, how about we do make this a core tips.module, but have it to *not* be enabled in the minimal installation profile. Some might argue that they don't want it in the standard profile either, but newbies would possibly not know how to go enable it (or any other module) in the first place. So, I believe that a good middle ground is to either offer an additional (optional) "Also enable tips" checkbox when selecting the standard installation profile or enable it by default in the standard profile but make sure we offer an opt-out on the welcome page right after installation. Does this sound ok?

As for only-core tips, I have to say I strongly disagree with that one. I believe that contrib would also benefit from an API-like way to offer tips with minimum effort. Ideally all they'd have to do is type the tips in a .tips or .help file and define where/when they want these tips to be shown. Site builders could also take advantage of such a system in order to provide tips for site visitors or authors/translators.

I agree that there should be a way for users to individually disable tips (once they've mastered a certain feature for example), but this needs to be a per-tip and per-user feature.

Aaand of course I'd also like to add:

Those are funny parodies of the M$ Paperclip :-)

And as eye-catching as the MS Paperclip is, it is definitely annoying how it pops up in your way. I don't think the tip messages should be in any kind of "pop-ups" -type dialogues; they should just be displayed as in the issue summary or as in http://drupal.org/comment/reply/1164760#comment-6448460

I also agree that:

1. It should be possible to install without the "tips" (standard profile, no tips in minimal)
2. It should support contrib, too.

Reposting from http://drupal.org/comment/reply/1164760#comment-6448460:

Point towards contrib solutions in context of specific functionality

For example, a pointer to Views on the content listing page or near the setting for amount of items shown in listing pages:

Or mention Display Suite on the 'Manage display' tabs for content types in Field UI:

Instead of referring to individual modules is too controversial, link to search results per category in http://drupal.org/project/modules:

I don't think that tips as discussed here are the right tool.

Even with the provided examples, the primary goal of them would be to 1) educate new users about new functionality, 2) where to find it, and possibly 3) how to use and extend it.

Typical tips fail on all three points — they don't have sufficient context to properly educate, they usually don't have sufficient space/room to properly explain things, they duplicate the help, and they already vanished when you could really need that tip you saw last week.

I think this needs to be split into two main problem spaces: A) Education. B) Contextual help.

On A)

Instead of tips, we once had a core issue with the idea of introducing a "guide", which I'm not able to find anymore. The idea was relatively simple:

Allow each module to expose sort of a task list/check list that educates the user about the new functionality, how to set it up, where to find its relevant pages; e.g.:

Node module allows to author and publish content of different types. Content types can have different workflows, permissions, and fields attached to them.

1. [x] Manage the content types you need.
2. [ ] Configure user permissions for each content type.
3. [ ] Create a content.
4. [ ] See existing content published to the front page.
5. [ ] Manage all existing content on your site.

This would live on a separate page; e.g., /admin/guide. It properly explains what you can do, it is persistent/re-entrant (so you can find it again to verify which steps you've not done yet), it automatically adapts to your user permissions (so it also works for users with less permissions), and it is modular, which means that a module could add a step for another module if necessary, but in general, each module gets its own set.

The system would automatically determine whether a user has performed a particular step, but also allow the user to manually set a step as done. Once all steps of a module have been performed and are known to the current user, the module's section would disappear, since you've learned how to use it.

It solves the problem of education not only for new Drupal users, but also for long-time users. (Just ask any developer what she/he is regularly doing in order to find out about a new module's functionality... ;))

I still think that this is a great idea and would love to help to design and develop it. (In terms of development, the functionality is anything but trivial. ;))

On B)

I also think we have at least one issue discussing how to introduce contextual help in the form of tooltips to specific page elements. Those tooltips would be conditional; i.e., they'd adapt based on what the current options/settings of something are.

Their primary purpose is to guess/foresee questions that a user might have when looking at a specific element on the page. With regard to that, they might appear similar to the "Did you know?" tips discussed here. However, the tooltips would never appear in a global scope/context, but always attached to certain element instead. To keep their usage small and focused, each tooltip would always require at least one constraint/condition in order to exist ("if this then that"), so it wouldn't be possible to permanently show a tooltip that says "Go here to to add a content type."

I'm not sure on that idea (but I believe that the contrib Advanced Help module supports something that's at least similar).

Re-reading comments on this issue once more, it seems I overlooked: C) Cross-references

Thus, continuing my last comment:

On C)

Most of the problems that @yoroy pointed out as examples are actually very simple cross-reference links. The one and only one that currently exists in HEAD is the "Add content" link on /admin/content — i.e., the administrative content view has a cross-reference link to the page that allows to add new content. The reverse, a back reference link, does not exist.

Unlike options A) and B) in #27, cross-reference links could actually be achieved in a very simple way, and they could easily have a big impact on first-timer as well as long-timer user experience. Because, regardless of your pay-grade, they would be a super-handy navigational tool to get from place A to a closely related place B.

As such, they'd be similar to contextual links, but not identical. Contextual links provide links to perform administrative operations on an element that is currently viewed. They act on dynamic entities only.

Cross-references would provide links between pages that may not have a direct, technical connection, so as to refer to functionality that is technically not related to the current page, but logically it is closely related. They would act on static pages only (mostly administrative, but including /node/add).

They would also be bi-directional; i.e., it doesn't matter whether the reference is declared as node/add => admin/content or vice-versa — the cross-reference automatically exists both ways, and there'd be a link on each of both pages.

Technically, this should be stupidly simple to implement (just an associative array of mapped paths returned by a new hook or whatever; the title and everything else is automatically extracted from the router, including access check). Ideally, we would immediately "componentize" this as a de-facto thing that themes should cater for; i.e., just like action links and local tasks/tabs (which aren't proper components yet, but should be).

Interesting idea.

You could define it in hook_menu().. Have a 'link-to' key, with an array of paths to content relevant to the current page. The menu system would then look through the link-to arrays to see if the current path is listed as a back link, and then generate the back link.

There wouldn't be a UI for managing them, other than to maybe turn them off; they'd be code-only. Modules could do a menu alter and add their own cross-links to existing paths.

Something like that? :-)

Yeah. I specifically did not consider hook_menu() though, since the menu router and related functionality is currently undergoing a major refactoring, and the folks who are working on that are trying hard to do the opposite: Remove everything that doesn't strictly belong to routing functionality. ;) In short, hook_menu() will cease to exist for D8.

Thus, to avoid running into blockers/problems there, I guess we'd simply introduce a new hook that returns the cross-reference link mapping; e.g., largely based on @yoroy's examples in #18:

function node_crossreference_info() {
  return array(
    // Add content vs. Manage content.
    'node/add' => 'admin/content',
  );
}

function system_crossreference_info() {
  return array(
    // Site name vs. Site logo.
    'admin/config/system/site-information' => 'admin/appearance',
  );
}

Obviously, we'd need a better hook name; e.g., hook_related_paths(). Btw, @yoroy called this "Places to go", so perhaps hook_places_info()? ;)

One further consideration struck me: Those cross-reference links would be "multiple per path", by design. I tried to think of further possible examples for node/add or admin/content, and the per-content-type user permissions quickly crossed my mind; e.g.:

function node_crossreference_info() {
  return array(
    // Add content vs. Manage content.
    'node/add' => 'admin/content',
    // Manage content vs. Content type permissions.
    'admin/content' => 'admin/people/permissions',
    // Manage content types vs. Content type permissions.
    'admin/structure/types' => 'admin/people/permissions',
    'admin/structure/types/manage/%node_type' => 'admin/people/permissions',
  );
}

We'd have to clarify whether such usage would be appropriate. And if so, we'd have to think about the consequences:

1) There would be plenty of crossreferences to the Permissions page. The bi-directional idea should probably be dropped then, so many pages can reference Permissions, but the Permissions page does not reference back to all of those pages. ;)

2) It's possible that we need to specify more than paths, since most of the target paths have very generic titles such as "Appearance" or "Permissions" — whereas the relation to the current page might not be obvious for the user. I.e., in @yoroy's concrete example, the helpful part was to point out that the site logo is configured somewhere else than the site name — but a link labeled "Appearance" certainly won't pull the trigger for anyone. ;) At the same time, custom link labels will quickly run into the problem of: What if there are multiple related things on the same target page — and two different modules want to point to different things on the target page. That would mean there'd be multiple links à la "Configure site logo" that all point to the same target page, but for different purposes.

Theme-implementation-wise, off-hand, I don't have a concrete idea for how those related links could be exposed. I originally imagined them like action links (because we're abusing action links for that only existing link we have in HEAD right now), but I think that would be detrimental for the "real" action links (typically "Add foo"). A second consideration was to use a dropbutton in a special location. And a third consideration was to turn this into a block that could be placed into a custom region and be styled in many different ways. (As the maintainer of admin_menu, I'd consider to move these links into the dropdown menu.)

Overall, this needs some more thought and careful planning. But I do think that cross-reference links would definitely help to solve the major problem of discovering functionality, which definitely becomes only larger and larger as we're abstracting more and more things in Drupal.

This could be useful I believe: #1809352: Write tour.module and add it to core

Also #1921152: META: Start providing tour tips for other core modules. could help with #26

"Did you know?" help tips are essentially covered by the new Tour module and its "tips."

However, what's not covered yet is the possibility of cross-reference links as a tool for both novice as well as advanced users, as alluded to from #27 and onwards.

Perhaps we want to rename/relabel this issue?

Set input format to an accessible one.

Updated issue summary.

Updated issue summary.

Perhaps when Help Topics is stable, links to topics can be integrated in specific places in the UI. Since help topics *do* have bi-directional related topics, this might help a user get to a section of help that is relevant to the task they want to complete, and then be able to learn more through selecting related topics.

For example, on content/add, adding help text with a link to admin/help/topic/node.creating_content (currently in the 9.4.x file system at core/modules/help_topics/help_topics/node.creating_content.html.twig), which has a link list of related topics including creating a new content type as well as other content admin tasks.