Follow-up to #2570997: [Meta] Update the module descriptions on the Configuration page

Problem/Motivation

The explanation texts on the Structure pages invite the user to do something, for example to manage or configure something.
Some of these texts don't follow the common format, as described in the Help text standard

Proposed resolution

Change the descriptions in thet *links.menu.yml files that they are correct, consistent, and follow a common format.

Remaining tasks

  • Compare the explanation text of each item with the help text for the module that provides this.
  • Check the format of the explanation text. Does it
    • start with a verb, second person singular (Configure, Manage, Translate etc.);
    • is it short and concise;
    • does it end with a full stop (.)

    .

User interface changes

This is a UI text change.

API changes

None.

Data model changes

None.

Beta phase evaluation

<

-->

Reference: https://www.drupal.org/core/beta-changes
Issue category Task because it makes the link descriptions for modules clearer and consistent.
Issue priority Normal
Unfrozen changes Unfrozen because it only changes strings in the link descriptions.
Disruption None

Comments

ifrik created an issue. See original summary.

ifrik’s picture

Issue tags: +Usability
duaelfr’s picture

Issue tags: +Novice
yoroy’s picture

Priority: Normal » Minor

"Manage content types, including default status, front page promotion, comment settings, etc."
for Content types,
"Add new menus to your site, edit existing menus, and rename and reorganize menu links."
for menus,
could be made a bit more to the point.

"Configure what displays are available for your content and forms."
For Display modes is using the same words to explain which is not so helpful.

I don't see any big issues with the current state though.

Andrew Gleeson’s picture

I am currently working on this at Drupalcon Barcelona FIRST TIME sprint session

Andrew Gleeson’s picture

I am working alongside Mairi Fraser (mairi) who is doing the same for the below issue:
https://www.drupal.org/node/2570997
This is the contributor task that we *think* we're doing:
https://www.drupal.org/node/2276597

The attached file lists the *links.menu.yml files that need to be reviewed and updated where required, identified using the following command:
find . -name "*links.menu.yml" -print | xargs grep "parent: system.admin_structure" | awk -F: '{print $1}' | sort -u > 2570997-files_list.txt

All files listed are currently marked as TODO - We will update as DONE the ones that we get through today

Andrew Gleeson’s picture

Status: Active » Needs work
StatusFileSize
new1.2 KB
new1.5 KB

This patch attempts to address the first 2 points in #4.

It's not clear to me what needs done about the 3rd point, so I have not done anything there.

See files list attached with files which have been checked.

ifrik’s picture

Status: Needs work » Needs review
ifrik’s picture

Status: Needs review » Needs work

Thanks for the patch, but I suppose comment #4 meant to make the description text shorter, rather then adding more information to it.
The reference to "comment settings" is probably still left over from Drupal 7, but makes less sense now that comments are a field.

How about this:
Content types
Create content types and manage their default settings.

Taxonomy
Configure vocabularies and taxonomy terms.
That way site builders who have already come accross vocabularies in other parts of the site, recognize the link easier; rather then explaining what taxonomy is used for.

rajeevk’s picture

Done as per suggestion in #10. Attaching patch & interdiff..

rajeevk’s picture

Status: Needs work » Needs review
ifrik’s picture

Issue summary: View changes
Status: Needs review » Reviewed & tested by the community

Thanks RajeevK for the update of the patch.

It all looks good. The link descriptions are consistent and follow the same format. They are all a bit shorter then before, but still give the relevant information.

I think this is ready to go.

beta evaluation added

jhodgdon’s picture

Status: Reviewed & tested by the community » Needs review

Hm.
Manage menus and menu links for your site.
Do we really need "for your site" in there? Everything is for your site.

Also:

-  description: 'Manage tagging, categorization, and classification of your content.'
+  description: 'Configure vocabularies and taxonomy terms.'

I actually thought that the previous description was useful, because maybe someone doesn't know what "vocabularies" or "taxonomy terms" are, but they probably know what tagging and categories and classification mean.

Bojhan’s picture

Can we please be careful that we are not removing months of hard work in the Drupal 7 cycle? We spend a lot of time on copywriting, I find the latest slew of issues often not taking that part of usability into account and very hard to review.

I agree wholeheartedly with jhodgdon here.

jhodgdon’s picture

Status: Needs review » Needs work
rajeevk’s picture

Status: Needs work » Needs review
StatusFileSize
new1.07 KB
new1020 bytes

Done as per ongoing discussion.

ifrik’s picture

Status: Needs review » Reviewed & tested by the community

Thanks for the updated patch.
I thought using "vocabularies" here would be good, because the term comes up at other places, and users might look for that, but I also see the reasons for talking about classification etc.

Since this takes up the issues raised, I think it's ready to go.

jhodgdon’s picture

+1, these two changes seem fine to me. Much more concise without losing information or readability.

Bojhan’s picture

Great :)

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 16: 2570999-module-description-structure-page-16.patch, failed testing.

jhodgdon’s picture

Status: Needs work » Reviewed & tested by the community

Test bot failure.

xjm’s picture

Status: Reviewed & tested by the community » Fixed

Thanks everyone for your work on this issue.

Can we please be careful that we are not removing months of hard work in the Drupal 7 cycle? We spend a lot of time on copywriting, I find the latest slew of issues often not taking that part of usability into account and very hard to review.

I believe this was referring specifically to the changes for the Taxonomy help text, which I agree were problematic. I infer from @Bojhan's comment in #19 that the other two changes are okay in the current patch:

  1. +++ b/core/modules/menu_ui/menu_ui.links.menu.yml
    @@ -1,5 +1,5 @@
    -  description: 'Add new menus to your site, edit existing menus, and rename and reorganize menu links.'
    +  description: 'Manage menus and menu links.'
    

    The extra words in this one didn't add any information, so I think this one is fine.

  2. +++ b/core/modules/node/node.links.menu.yml
    @@ -1,7 +1,7 @@
    -  description: 'Manage content types, including default status, front page promotion, comment settings, etc.'
    +  description: 'Create content types and manage their default settings.'
    

    This one is losing examples of what those default settings might be. However, the comment settings actually aren't managed there anymore anyway, so the updated text is more accurate. So I think this one is still an improvement (again with the assumption that Bojhan signed off on it above).

So based on that assessment and the overall improvement, it seems to get this in before string freeze. Committed and pushed to 8.0.x. Thanks!

  • xjm committed 02cc907 on 8.0.x
    Issue #2570999 by RajeevK, Andrew Gleeson, ifrik, jhodgdon, Bojhan,...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.