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 don't follow the common format, as described in the Help text standard; others are not correct anymore for Drupal8, are somewhat convoluted or confusing, or don't give the user any additional information that isn't already given in the module name.
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.

Proposed resolution

Change the descriptions in the *links.menu.yml files that they are correct, consistent, and follow a common format. Because these can result in more changes then what is easy to review, this should be split up into several issues of different priority but without possible conflicts

Remaining tasks

Update the link descriptions in the child issues.

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 Bug because the User interface was changed, but the help text was not changed accordingly
Issue priority Minor
Disruption None
Files: 
CommentFileSizeAuthor
#28 drupal_core-module_description-2570997-28-D8.patch13.09 KBsnehi
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,235 pass(es). View
#26 2570997-module-description-configuration-page-26.patch12.66 KBifrik
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,481 pass(es). View
#26 interdiff-24-26.txt0 bytesifrik
#24 2570997-module-description-configuration-page-24.patch12.61 KBifrik
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 114,491 pass(es). View
#24 interdiff-14-24.txt7.27 KBifrik
#16 screenshot-2570997-after-14.png199.47 KBrachel_norfolk
#14 2570997-files_list.txt1.4 KBmairi
#14 2570997-module-description-configuration-page-14.patch8.16 KBmairi
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 114,334 pass(es). View
#12 2570997-files_list.txt1.07 KBmairi
#4 2570997-module-description-configuration-page-4.patch4.44 KBifrik
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,979 pass(es). View

Comments

ifrik created an issue. See original summary.

ifrik’s picture

Issue summary: View changes
ifrik’s picture

Working on this during DrupalCon.

ifrik’s picture

Status: Active » Needs work
FileSize
4.44 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,979 pass(es). View

I've checked everything that is displayed on the Configuration page in a minimal install, but the rest still needs to be done.

snehi’s picture

Assigned: Unassigned » snehi
snehi’s picture

Issue summary: View changes
snehi’s picture

DuaelFr’s picture

Issue tags: +Novice
peterg.griffin’s picture

Is this task still being worked on?

peterg.griffin’s picture

Assigned: snehi » Unassigned
mairi’s picture

Assigned: Unassigned » mairi

I will pick this up (DrupalCon Barcelona 2015 mentored sprint - first time sprinter!) and see if I can do some more work on the patch.

mairi’s picture

FileSize
1.07 KB

This is the contributor task I *think* I'm 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_config" | awk -F: '{print $1}' | sort -u > 2570997-files_list.txt

All files listed are currently marked as TODO - I will update as DONE the ones that I get through today (including those that have already been picked up by ifrik).

ETA: working with Andrew Gleeson who has picked up related issue 2276599 and is also a first time sprinter

ifrik’s picture

Thanks Mairi,

that looks like a good way of structuring it.

mairi’s picture

FileSize
8.16 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 114,334 pass(es). View
1.4 KB

This patch includes UI help text changes for files marked as STATUS = DONE and CHANGED = Y in the attached files list txt file. I have checked most, but not all, of these changes in a clean Drupal 8 install. In some cases I couldn't figure out where the description would appear in the interface.

First time sprinter, so hopefully I haven't changed anything I shouldn't have or made anything worse!

mairi’s picture

Status: Needs work » Needs review
rachel_norfolk’s picture

Attached a screenshot after #14 and the changes of help text to match standards do appear to have been applied.

rachel_norfolk’s picture

Status: Needs review » Reviewed & tested by the community

I have also reviewed the code and the only items that are changed are the descriptions and they do all match the the help text standard.

rachel_norfolk’s picture

Issue summary: View changes

Adding a beta evaluation.

ifrik’s picture

Title: Update the module descriptions on the Configuration page » Update the hook_help for the block module again
Assigned: mairi » Unassigned
Category: Task » Bug report
Issue summary: View changes
Status: Reviewed & tested by the community » Needs work
Issue tags: -Novice
Parent issue: #2499495: [meta] Review UI text for D8 core modules » #1908570: [meta] Update or create hook_help() texts for D8 core modules
Related issues: +#2499495: [meta] Review UI text for D8 core modules

Thanks a lot Mairi for the patch and Rachel for the review and beta-evaluation.

All the changed texts look good.

There are a few more descriptions on the site that I would like to edit as well, such as the Ban module, so I re-open the issue, and I can work on that tomorrow during the Extended sprint.

ifrik’s picture

The last submitted patch, 14: 2570997-module-description-configuration-page-14.patch, failed testing.

ifrik’s picture

Title: Update the hook_help for the block module again » Update the module descriptions on the Configuration page
Category: Bug report » Task
Issue tags: +Novice

Wow... I managed to change a lot of issue meta data without intending to do so.
This should be correct now again

ifrik’s picture

Status: Needs work » Needs review
Issue tags: +Needs usability review
FileSize
7.27 KB
12.61 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 114,491 pass(es). View

I've reviewed and changed some more of the texts: either because they were not quite correct anymore or less clear then they could be.
I've tried to keep wording consistent with the hook_help texts.

jhodgdon’s picture

Status: Needs review » Needs work

Looking pretty good! A few suggestions:

  1. +++ b/core/modules/aggregator/aggregator.links.menu.yml
    @@ -1,6 +1,6 @@
    +  description: 'Add feeds to gather external content and configure how often they are updated.'
    

    I think "add feeds" is misleading here -- it sounds like you would be *providing* a feed from your site.

    The previous description did not have this problem of being possibly misleading.

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

    I think you can also ban ranges of IP addresses with *, can't you? maybe not... this may be overly specific?

  3. +++ b/core/modules/config_translation/config_translation.links.menu.yml
    @@ -1,6 +1,6 @@
    -  description: 'Translate the configuration.'
    +  description: 'Translate configuration items.'
    

    hm, really, configuration items? How about just

    Translate site configuration

  4. +++ b/core/modules/image/image.links.menu.yml
    @@ -1,5 +1,5 @@
    +  description: 'Configure styles to manipulate the display of images.'
    

    Could be shortened to

    Configure image display styles

  5. +++ b/core/modules/language/language.links.menu.yml
    @@ -1,6 +1,6 @@
    +  description: 'Configure languages for content, interface and configuration.'
    

    needs comma before "and"

  6. +++ b/core/modules/path/path.links.menu.yml
    @@ -1,6 +1,6 @@
    +  description: 'Add custom URLs to existing internal paths.'
    

    Will people know what "internal paths" are?

  7. +++ b/core/modules/simpletest/simpletest.links.menu.yml
    @@ -1,6 +1,6 @@
    +  description: 'Run tests against the site core code and enabled modules to assure that your code works as designed.'
    

    assure is not right here.

  8. +++ b/core/modules/system/system.links.menu.yml
    @@ -40,14 +40,14 @@ system.admin_config_media:
    +  description: 'Set paths to store uploaded files, including translation files, and configure how they are accessed.'
    

    paths? Really it's directories on the web server, I think?

  9. +++ b/core/modules/system/system.links.menu.yml
    @@ -56,7 +56,7 @@ system.admin_config_services:
    +  description: 'Configure the description and content of feeds provided by the site.'
    

    hm. Does it really affect all feeds (created by Views for instance, which is now in core) or just some specific ones?

  10. +++ b/core/modules/system/system.links.menu.yml
    @@ -67,19 +67,19 @@ system.admin_config_development:
    +  description: 'Clear caches, configure page caching for anonymous users, and enable bandwidth optimization for CSS and JS files.'
    

    JS -> JavaScript

  11. +++ b/core/modules/system/system.links.menu.yml
    @@ -91,26 +91,26 @@ system.admin_config_regional:
    +  description: 'Set whether the site has a default country and timezone, and whether users can set their own timezone.'
    

    maybe remove "whether the site has a"?

  12. +++ b/core/modules/system/system.links.menu.yml
    @@ -91,26 +91,26 @@ system.admin_config_regional:
    +  description: 'Configure local site search, metadata and SEO.'
    

    comma before "and"

ifrik’s picture

Status: Needs work » Needs review
FileSize
0 bytes
12.66 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,481 pass(es). View

Thanks for the review. This looks like we could have reviewed these description coming from D7 earlier :-)

1. I used "add" here because that is the action the user on the linked page. The previous formulation was really cumbersome. I tried to get around a possible misunderstanding by adding the "import OPMLs" as well.

2. I replaced "individual" by "specific" - that leaves the question whether you can ban visits for blocks a bit more open.

6. I used "internal" to make the it clear that it's only within the site, and different from linking to anything outside.

7. I've used the previous wording of "help you to assure".

9. This looks like a real legacy issue. The page only configures one feed - accessible at rss.xml - but actually this feed is created by feeds as well. (The UI text of this page should be checked and edited as well.)

11. I left the "a" infront of default time zone on purpose, because you can also set it not to have a default time zone.

jhodgdon’s picture

Careful about assure/ensure:
http://www.quickanddirtytips.com/education/grammar/assure-versus-ensure-...
I think anything we do in the Drupal UI is about "ensure", not "assure", right?

snehi’s picture

FileSize
13.09 KB
PASSED: [[SimpleTest]]: [PHP 5.5 MySQL] 113,235 pass(es). View

Updating with spell check, suggestion from Jhodgdon, removing additional commas etc.
Please review.

Bojhan’s picture

I am not convinced of almost 50% of these changes. Can we discuss this over IRC? This patch is almost to big to review.

jhodgdon’s picture

Status: Needs review » Needs work

Meanwhile, setting status...

snehi’s picture

Can u suggest @Bojhan

ifrik’s picture

Snehi,
just a short comment: can you in future leave the patch name as it is because otherwise it's difficult to know whether a new patch is just an edited version of an existing one or a completely new one, and can you also provide an interdiff, so that reviewers know what has been changed?
No need to do that now anymore because I'm just about to split the issue up, but good practice in future.

ifrik’s picture

Title: Update the module descriptions on the Configuration page » [Meta] Update the module descriptions on the Configuration page
Issue summary: View changes

Apparently I hit "Restore last input" at some stage, and it restored the last input from another issue that was open, so the issue summary got totally messed up, and I only fixed some of that previously.
I've now restored that and turned it into a meta issue that can be reviewed more easily.

ifrik’s picture

I've split up the link descriptions in four issues depending on their priority, keeping all from the System module in one issue.
That should make it more easy to see why they were changed and to review them.

@snehi: I've put some of the commas back, because according to our style guide we need them.

jhodgdon’s picture

Category: Task » Plan
Status: Needs work » Active

Updating this issue then.

So... Everyone who supplied a patch on this issue, you might want to go to the child issues and add a comment so you can be credited for the child issue patches. If you only worked on part of the patch, pick the appropriate child issue.

Bojhan’s picture

Issue tags: -Needs usability review

Reviewing on the lower level issues.

Bojhan’s picture

Issue tags: -Needs usability review

Reviewing on the lower level issues.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

ifrik’s picture

Issue tags: +Dublin2016
joelpittet’s picture

Issue tags: +Needs followup

This needs follow-up issues created for the patch above as mentioned by @jhodgdon in comment #35

tkoleary’s picture

Kifah Meeran’s picture

Status: Active » Fixed
Issue tags: -Barcelona2015

Since all child issues have been closed, I'm going to close this one as well. Please feel free to re-open if required.

Status: Fixed » Closed (fixed)

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