Shorten help text on User Roles page

#1: 1952064-1-roles-help-text.patch queued for re-testing.

Thanks! I also wanted to create an issue for that, but always forgot to do so...

Two issues:

1) I think the very first mentioning of the term "role" should be "user role". That is, because a "user role" is linguistically and technically more specific and provides more topical context than just "role". Later on, we can just use "role".

2) What always annoyed me about this help text (since D6) is that the point about "order from least to most permissive" is absolutely unclear, since it does not state in which order — top to bottom or bottom to top?

3) Lastly, I've no idea where the ordering of roles is actually used, and whether it has any (serious) impact on anything... — off-hand, I only know about two places where a list of roles appears: 1) In the table header on the Permissions page. 2) Checkboxes on the user account edit form. The order for both of these is purely cosmetic. I don't know whether there are other places and whether the order is of any technical importance.

The test failures are random and can be safely ignored here. Let's move forward with doctoring on the copy text. :)

eeek, no, the test failures are real — the patch in #1 is not the patch you wanted to upload ;)

The patch successfully applied, no grammatical errors found.
+1

+++ b/core/modules/user/user.moduleundefined
@@ -68,13 +68,7 @@ function user_help($path, $arg) {
-      $output .= '<li>' . t("Anonymous user: this role is used for users that don't have a user account or that are not authenticated.") . '</li>';
-      $output .= '<li>' . t('Authenticated user: this role is automatically granted to all logged in users.') . '</li>';

I think this text very useful. This roles could not be deleted and their behaviour is special

totally agree with @andypost , we should probably add that back. Maybe we can concatenate the lines into something like :
'user is granted Authenticated or Anonymous user role automatically whether he is logged in or not'.

New patch with token replaced and usage of \Drupal::url()

Interdiff from comment #9

We have a separate issue where the help for the user module as a whole is being edited. This patch should only address changes to the help on the Roles page.
#2103043: Review hook_help for the user module
If you want to make edits to the main help text only, then close this issue as a duplicate and make the changes on the other issue please.

And can someone update the user summary and the title here? The title/summary imply we want to shorten the roles page, but this patch is adding a new line to the help and not making it shorter in the way described. Why?

Note: I just found this issue today so all I read was the summary and the latest patch.

We just had a change to hook_help, on this issue: #2183113: Update hook_help signature to use route_name instead of path.

Here is the change record: https://drupal.org/node/2250345

This patch will need a reroll for this change.

Also the other issue about the user module help has been finished.

This patch contains changes to user roles help only.

Corrected patch. Shouldn`t we fix all url() calls here?

Thanks! This patch looks good. And yes, if you could go through all of user_help() and fix the url() calls (which we missed in the previous issue), that would be great!

Also, there were several suggestions made on this help text in previous comments... Maybe comments #11/12 should be addressed, so that we explain a bit about the special Anonymous and Authenticated roles? The idea of help on top of pages should be to explain concepts that are not obvious, and I think this qualifies.

Also, maybe (reading through the comments about ordering above) instead of suggesting a particular ordering, we should just say that the order here will be used as the column order on the Permissions page? That will tell people why they would want to put them in order.

Added text from #12 and converted missed url() calls.

Thanks, looking pretty good. A few things to fix:

a) On permissions page:

See the <a href="@role">Roles</a> page to create a role ... array('!role' => 

The a href needs to be !role here

b) On permissions page:

Authenticated Users and Administrators

The actual names of these roles are "Authenticated user" and "Administrator". We need to refer to them how the user sees them (same on the Roles page).

c) On roles page:

User is granted Authenticated or Anonymous user role automatically whether he is logged in or not

This is not clear. I think I would say something more like: "Users who are not logged in have the Anonymous user role. Users who are logged in have the Authenticated user role, plus any other roles granted to their user account.".

I can help with this.

Feedback welcome!

Looks pretty good, thanks!

A few nitpicks:
a)

(See the <a href="!role">Roles</a> page to create a role).

The . should be before the ) since the whole sentence is parenthetical.

b)

... Authenticated user role will be given to any user who can log into your site.

Technically it is not any user who *can* log in, but any user who *is* logged in.

c)

 You can make any role the Administrator role for the site, meaning this will be granted all new permissions automatically. You can do this on the <a href="@settings">User Settings</a> page.

Can these two sentences be combined? Seems choppy.

d)

It is recommended to order your roles from least permissive (anonymous user) to most permissive (administrator).

These roles should be capitalized same as they appear on the Roles page.

This should address the feedback in #28.

Feedback welcome!

Whoah, the interdiff from #29 didn't work. :S I'll generate a different one... sorry about that.

That's OK about the interdiff, it's a small patch anyway.

Anyway, this text looks good to me. We probably need a manual test to make sure:
- The links all work
- The UI text (page names, role names, etc.) in the help matches what you see. I'm a bit concerned about page names ... for instance the Permissions page is probably capitalized, and the "User settings" page probably does not have two capital letters in its name?

I can't RTBC this because I helped write a patch; but I will look into the page names, role names etc. right now.

Manual testing has verified all the links work. I've fixed the inconsistencies with page names.

Note the interdiff-27-29 file is a replacement for the broken interdiff in #29.

Thanks! This looks really good, and I was surprised (and pleased) to see that you went back to the main hook_help text and updated it too.

I only have one concern now. The Standard install profile creates a role called "Administrator", which is also set to be the "Administrator role". (The Minimal install profile does not create this role, and no role is set to be the "Administrator role".) Anyway... this is a confusion of names/terms, between the specific name of the role that is created by some install profiles, and the setting that says "which role should automatically get new permissions when modules are enabled". I don't think the help text makes this distinction clear, and I also think it implies that "Administrator" is on the same footing as "Authenticated user" and "Anonymous user" -- which isn't true, since auth/anon exist for any Drupal install, and admin is only created by some install profiles.

I'm not sure how to fix this right now but... I think something needs to be done?

I re-worded the text so it sounds like the Administrator role may or may not be on your site.

I also found one more case where the Account settings page was referred to as the User settings page (it was in user.admin_permissions), so I fixed it.

Feedback welcome!

Looks pretty good!

I'm not sure about this text about the Administrator role in the main module help:

... users with this role are registered, logged in, and will automatically be assigned any new permissions...

I think we could leave out the "are registered, logged in, and" part? I just went "huh?"

Also filed a follow-up issue:
#2280521: User module help needs improvement

Removing "are registered, logged in, and" sounds like a good idea to me. See the change in the attached patch.

Hmm...

I'm not really sure what the difference between this patch and #2280521: User module help needs improvement is anymore... I guess this one technically started out as "Shorten help text on User Roles page" but it's kinda evolved into "update hook_help() for the User module" (note that this scope creep is totally my fault: I started changing all the things in #33 — sorry about this :S).

Should I split off the changes not specifically in case 'user.role_list' and put those in #2280521: User module help needs improvement?

RE split of issues... I filed a different one because I noticed a couple of things and didn't want to scope creep this issue that was practically done. But yes, probably we should either (a) close the other issue as a dup, change the title of this issue, and officially scope creep it, or (b) move the unrelated changes to the other issue (add them to the summary).

Your choice, since you've been working on this issue. :)

I'll split it up into two pieces.

Okay, here's only the changes in case 'user.role_list' (I did not make any changes to text; I just split out that particular segment). I'll post the other changes in a patch to the other issue shortly.

Last patch looks good. However, you don't need the semicolons after e.g. (http://en.wiktionary.org/wiki/e.g.) and after having a non-drupal person read it, a "top of the list" comment would make it clearer over all.

Maybe something like this:
... It is recommended to order your roles from least permissive at the top of the list (e.g. Anonymous user) to most permissive at the bottom (e.g. Administrator).

I am going to review this patch!!

Can we instead please just remove "e.g." entirely? Just say "for example," and please use a comma after it.

I'm reviewing this at the Austin sprint.

Also updating to rewording the text in the semicolon area.

Removed the semicolon in the brackets.

(e.g.: Anonymous user) to most permissive (e.g.: Administrator)

Also updated

In this area you will define the names and order of the roles on your site.

to

In this area you will define the names and the display sort order of the roles on your site.

to address comment #42.

While I am not much a linguist - the patch from #46 applies fine, accomplishes the stated changes, and makes sense to me.

RTBC +1

I just tested this and the patch reflects the changes made. Abbreviated text works well.

I am working on the patch #44 to change it to 'for example' instead of "e.g"

I am submitting the patch

Austin Sprint Review!!

Fixed the last patch. Updated e.g. to for example

Pulled origin 8.x and rerolled patch.

Recreated the patch!!

Recreated the patch, missed to the upload files!!

Reviewed and tested on SimplyTest.me and it looks good. All "e.g." was replaced with "for example, ".

Thanks @jonried and @prabeen.giri, patch in 56 looks good!

Thanks, I agree it looks good!

Works for me! Thanks! Good change.

Changed @setting to !setting. I looked in this https://www.drupal.org/node/1908570 and this mentioned two issues :- https://www.drupal.org/node/2103043 and https://www.drupal.org/node/1952064. One is already in fixed state. So, I think it is better to do this change here.

OK. It would have been better in this case to file a new issue, because we do not usually like to have patches on issues that contain unrelated changes. But this patch is correct and is a one-character fix, so let's just go with it...

Thanks again everyone! Committed to 8.x.