Needs better documentation.

Due to the wording on the Permissions page, the permissions don't really make sense as to what does what or why. These need to be explained somewhere.

On the config page, you're met with dropdowns of Safe, Unsafe or Create Permission. /admin/config/people/administerusersbyrole There is zero help text on what this is for. After playing around, I was able to figure out that this "shows / hides" a role on a user edit screen. Without playing around, it was scary to set this to anything other than leaving it at "unsafe". So what does "Create Permission" do? Don't have time to figure it out.

I don't mind helping with docs, but a) I don't have time to play with the module to "figure it out" by reverse engineering how it works. b) Without existing documentation, I can only speculate what permissions or settings do, so it doesn't make sense to write anything up when I don't actually know how it works.

CommentFileSizeAuthor
#9 administerusersbyrole.help-role-config-3044984-9.patch10.42 KBadamps
#8 administerusersbyrole.help-role-config-3044984-8.patch8.13 KBadamps
#7 link-help-role-config-3044984-7.patch910 bytesfeng-shui

Comments

philsward created an issue. See original summary.

adamps’s picture

adamps commented

Main module documentation is in the usual place at admin/help/administerusersbyrole.

Patches welcome.

philsward’s picture

philsward commented

Heh... 12 yrs of using Drupal and there's the "help" menu...

Honestly, I never look there because most folks either don't add docs, or it's so vague it's not worth checking.

I haven't looked over those docs yet, so I'll post back if I feel like it needs better clarification.

Maybe add a link from the admin/config pages?

adamps’s picture

adamps commented

Maybe add a link from the admin/config pages?

Sure - patches welcome:-)

If you aren't planning to post a patch then I'd like to close the issue as "works as designed" - I'm trying to keep on top of the issue queue.

philsward’s picture

philsward commented
Status: Active » Closed (works as designed)

I can't code, so we'll have to close this.

adamps’s picture

adamps commented
Status: Closed (works as designed) » Active

Actually I think it you are right and this is a good idea, so let's keep it open.

I think it should be possible to add a link to the help page from admin/config/people/administerusersbyrole.

Hopefully I'll get time some day!

feng-shui’s picture

feng-shui commented
Status: Active » Needs review
StatusFileSize
new link-help-role-config-3044984-7.patch910 bytes

I was configuring this module today and was thinking that the form needed some docs, read the module page, found the help and thought a link to the help on the config form would be good. Patch does that.

adamps’s picture

adamps commented
StatusFileSize
new administerusersbyrole.help-role-config-3044984-8.patch8.13 KB

Thanks @Feng-Shui

I have created a more sophisticated patch based on the same idea

  1. Alter the names of the permissions to be clearer: "Edit users with safe roles" instead of "Edit users by role"
  2. Put the new help text in the help region and expand it with the relevant part from the main help

Please can someone review and let me know if it is clear or any suggestions to improve it.

adamps’s picture

adamps commented
StatusFileSize
new administerusersbyrole.help-role-config-3044984-9.patch10.42 KB

  • AdamPS committed 5187acf on 8.x-3.x 
    Issue #3044984 by AdamPS, Feng-Shui: Documentation
adamps’s picture

adamps commented
Status: Needs review » Fixed

Status: Fixed » Closed (fixed)

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