Problem/Motivation

The explanation texts on the Configuration page invite the user to do something, for example to manage or configure something.
Some of these texts are somewhat convoluted or confusing.
In some cases, extensive reviewing of the hook_help text of a module has come up with explanations of Uses that are more to the point then the existing link descriptions.

Ban: unclear whether IP addresses are banned within the site (instead of the ban of visits from IP addresses)
Filter: unclear when the filtering happens (help text even explains that wrongly). Plus wrong format
Editor (when Filter is enabled): Confusing and convoluted)
Actions: Description doesn't add anything, so users who don't know what Actions are learn nothing from the description
Locale: not clear that it's both the import of existing translation and custom translation

Proposed resolution

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

Remaining tasks

Update the link descriptions of the listed modules.

User interface changes

This are UI text changes.

API changes

None.

Data model changes

None.

Beta phase evaluation

Reference: https://www.drupal.org/core/beta-changes
Issue category Task to improve the link descriptions of a few modules
Issue priority Minor
Disruption None
CommentFileSizeAuthor
#9 2578991-link-description-configuration-page-confusing-9.patch3.44 KBifrik
#9 interdiff-6-9.txt477 bytesifrik
#6 2578991-link-description-configuration-page-confusing-6.patch3.44 KBifrik
#6 interdiff-2-6.txt1004 bytesifrik
#2 2578991-link-description-configuration-page-confusing-2.patch3.47 KBifrik

Comments

ifrik created an issue. See original summary.

ifrik’s picture

ifrik
she/her
commented
Assigned: ifrik » Unassigned
Issue summary: View changes
Status: Needs work » Needs review
StatusFileSize
new 2578991-link-description-configuration-page-confusing-2.patch3.47 KB

I've updated the link description for the following modules: Action, Ban, Filter, Editor and Locale.
The Editor change is in the module file because it changes the existing text provided by the filter module.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Reviewed & tested by the community

ifrik says we should credit: mairi, snehi, rachel_norfolk for this patch as well as herself.

I think this patch is all good changes. Very straightforward improvements in wording. Thanks!

Bojhan’s picture

Bojhan commented

Wondering if we can drop all references to "site" throughout Drupal. Also here "for your site"? Kinda obvious.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Reviewed & tested by the community » Needs work

Good idea. Looking at these specific changes in the patch:

  1. +++ b/core/modules/action/action.links.menu.yml
@@ -1,5 +1,5 @@
+  description: 'Create tasks that can be executed by the site.'

    I'm not sure how to reword this to remove "by the site" here... needs an "actor" to mention to execute the actions? 

  2. +++ b/core/modules/ban/ban.links.menu.yml
@@ -1,6 +1,6 @@
+  description: 'Ban visits to the site from specific IP addresses.'

    Here I agree we could remove "to the site"

  3. +++ b/core/modules/statistics/statistics.links.menu.yml
@@ -1,6 +1,6 @@
+  description: 'Configure the logging of content statistics for your site.'

    Agreed we could remove "for your site" here.

ifrik’s picture

ifrik
she/her
commented
Status: Needs work » Needs review
StatusFileSize
new interdiff-2-6.txt1004 bytes
new 2578991-link-description-configuration-page-confusing-6.patch3.44 KB

1. I agree that for the Actions module "the site" is the actor, and therefore it needs to stay.

2. and 3.: Always happy to remove unneeded words.

Bojhan’s picture

Bojhan commented

How do you feel about referring to the "system" rather than "site" ?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I think for Actions the "system" makes good sense. I think the module description uses the word "system", or at least it does in a patch on a related issue #2570985: Update the module descriptions on the Extend page. Though actually, in my last review there I suggested for the module description:

Allows configuration of tasks to be executed in response to events

This is passive voice; maybe it should be:

Allows configuration of tasks for the system to execute in response to events.

So maybe here we could say:

Create tasks that the system can execute

Thoughts?

The rest looks good.

ifrik’s picture

ifrik
she/her
commented
StatusFileSize
new interdiff-6-9.txt477 bytes
new 2578991-link-description-configuration-page-confusing-9.patch3.44 KB

Sounds good.

I'm offline in the next days, so if this needs more work it would be good if somebody else does the changes.

snehi’s picture

snehi commented
Status: Needs review » Reviewed & tested by the community

@ifrik thanks for helping. Looks good now.
Any Suggestion anybody.
This is RTBC Now.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Status: Reviewed & tested by the community » Fixed

Looks like @Bojhan's comments were addressed. Love that we are no longer defining the term with the term itself in most of these. ;P

Committed and pushed to 8.0.x. Thanks!

  • webchick committed 29052a5 on 8.0.x 
    Issue #2578991 by ifrik, jhodgdon, Bojhan, snehi: Update link...

Status: Fixed » Closed (fixed)

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