Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
The System module provides five default menus with a description of either what they contain, or what the site builder should use the menu for.
We should try to make these descriptions more consistent so that site builders can more easily understand the differences.
Proposed resolution
Update the menu descriptions in the system.menu.*.yml files.
Remaining tasks
Decide on a consistent wording, and update the descriptions accordingly.
User interface changes
This is a UI text change.
API changes
None.
Data model changes
None.
Beta phase evaluation
| Issue category | Task because it improves the UI text for menus |
|---|---|
| Issue priority | Normal |
| Unfrozen changes | Unfrozen because it only changes strings in the description of menus provided by the system module. |
| Disruption | None |
| Comment | File | Size | Author |
|---|---|---|---|
| #34 | 2572621-35.patch | 2.4 KB | jhodgdon |
Comments
Comment #2
ifrikComment #3
rachel_norfolkworking on this at DupalCon Barceloba extended sprints over this weekend.
Comment #4
rachel_norfolkIn an attempt to achieve consistency, and to demonstrate both the contents and the likely location of each menu I've adopted the pattern "Links to xxxxxx, usually found in a/the yyyyy region."
Comment #5
rachel_norfolkComment #6
ifrikThanks for the patch and coming up with an idea how to make these descriptions more consistent.
Before
After
We usually don't refer to how something might be displayed because this can change depending on theme or distribution, but in this case it strikes a good balance to give sitebuilders a better idea what the differences between these menus might be.
The current text states that other modules might add links to the tools menu - if we want to mention something like this then it would also need to be added to the administration menu. (Rachel, I suppose the change that you showed me earlier was done in the GUI and not included in the patch?)
Requesting a usability review as well.
Note: The changes of this patch are only displayed after a site install.
Comment #7
rachel_norfolkYes, I will add that text to the patch this evening.
Comment #8
ifrikHi Rachel,
how about changing it the tools description to "links to tools intended for users" ? That way the difference between admin and tools menus would be more obvious, and then it also makes sense that contrib modules might add links to either menu.
Comment #9
rachel_norfolkYes, your suggestion in #8 does make sense and I have included it in the patch below.
I also wonder if we should alter the main help text to indicate what is being described by each menu item? Not sure if that is in scope of this issue, though?
Comment #10
rachel_norfolkOne comment I will make is I'm not sure about the line length in system.menu.tools.yml - not sure if we have a standard for yml files?
Comment #11
ifrikIf the main help text could be improved by changing as well, then it would be good to include it into the issue.
My concern when creating this issue was to improve the usability of the page and the modification of menus. Plus it will be easier to see how descriptions and help text go together instead having them in two issues.
Just edit the issue summary to include it.
Comment #12
ifrikTested on simpletest.me because changes only show up if the patch is applied before building the site.
The change looks good because now the difference between admin and tools menu is much clearer.
I think the help text is fine as it is because it gives additional information relevant for site builders that isn't otherwise obvious.
beta evaluation added, but it would be good to have a review from the usability team.
Comment #13
jhodgdonHm. So... I think this can be improved -- I found these descriptions really jarring to read, due to the wording and punctuation. Here's an example:
Links related to the active user account, usually in the secondary menu region
So the first part of this description is about the links. Then there is a comma. Then the second part is about where the menu as a whole is being displayed, and it doesn't have a new subject to explain the context shift. It is really jarring to read. Also... usually? How about just "often". So... I think it would be better like this:
Links related to the active user account; often displayed in the Secondary menu region
[note also the capitalization of Secondary menu region, which we should check on -- but regions on the Blocks placement page are I think normally capitalized with Sentence case right?]
One other nitpic: in the Admin menu, it says:
Links to administrative tasks, usually in the admin toolbar.
==>
admin => administrative
[admin is not a word]
Comment #14
rachel_norfolkYes, I like the proposals at #13 and https://www.drupal.org/node/632280 implies that capitalisation of objects like module names and regions would be desirable.
Comment #15
rachel_norfolkComment #16
jhodgdonI like these descriptions **much** better. Probably needs a Usability review, so I am not setting this to RTBC.
Comment #19
rachel_norfolkas suspected, the test failure was a transitory database issue. Resetting to In Review...
Comment #20
Bojhan CreditAttribution: Bojhan as a volunteer and commentedWe probably shouldn't be saying ;often displayed in X.
I know we all want to, but we should hack UI problems into our help text. The way to solve this properly is to create less of a disconnect between preview and administrative interface.
The other changes look fine.
Comment #21
Bojhan CreditAttribution: Bojhan as a volunteer and commentedComment #22
jhodgdonDo you think we should remove the "often displayed in" parts, or change them to something else? The previous text (before patch) said the links were for those areas...
Comment #23
Bojhan CreditAttribution: Bojhan as a volunteer and commentedWe cannot refer to place in the front-end. Sadly this is just too misleading, as your basically giving an approximation of where something ought to be. This is an established approach, feel free to look into the 100's of comment long region/block renaming issues. Because we don't provide that representation. Referring to the location, is like putting lipstick on a pig - the correct way of doing this is providing a preview of menu placements. I don't want to deviate from this establish approach in a issue like this, that should then be a wider discussion.
Comment #24
jhodgdonOK, great! That is a clear guideline. So we just need to remove all the "often displayed" parts.
Comment #25
rachel_norfolkI'll admit I'm finding it challenging to remove information likely to be really useful to a new user but I do appreciate the standards Bojhan revers to in #23 so here's a modified patch...
Comment #26
jhodgdonApparently this needs to be "rc deadline" because it changes translatable UI text strings
Comment #27
jhodgdonThis looks fine, thanks!
Comment #28
xjmI'm not sure about this one -- "Links to" makes it sound like the menu links to those things, as a verb, especially since the patterns for link descriptions (e.g. #2578995: Update the link descriptions on the Configuration page for the system module) start with a verb.
I guess the paradigm of starting with a verb doesn't fit, since a link takes you to an action, but a menu just contains stuff. Maybe "Links for" in all cases?
Thanks all!
Comment #29
rachel_norfolkHow does "Contains links to ..." grab people? Places the action on containing a collection of things.
Comment #30
jhodgdonI do not think this should be a verb. This is descriptions for the individual menus on the Menus page, and menus are "things" not "actors".
I agree with @xjm that "links to" sounds like a verb, so I agree "links for" is better, since it makes "links" sound more like a noun.
Comment #31
jhodgdonWhen I read all of these with "links for", they ... sounded very awkward. So. Here's another try...
Comment #32
jhodgdonfixing title - these are in system config
Comment #33
jhodgdonGot some semi-reviews in IRC, here's another patch.
Comment #34
jhodgdonSorry too much in that patch, try this one.
Comment #35
Bojhan CreditAttribution: Bojhan as a volunteer and commentedComment #37
xjmThe rewritten texts are all improvements as well. Committed and pushed to 8.0.x. Thanks!