Consider how roles and permissions can be intuitive, simple and safe for evaluators whilst later site owners can have full control

If we think there is scope to do more than minimal work on this then maybe it should be an additional track?

Moving to Drupal CMS

One possibility is to augment *.permissions.yml files so they have "extended_help" sections. For instance, webform.permissions.yml would have:

main:
  extended_help: These permissions deal with the webform module. You can probably use the default settings, however, if you want to do [ABC], you might want to [XYZ]. Another possible use case is [ABC2]. In that case you'd [XYZ2].

'access webform overview':
  title: 'Access the webform overview page'
  description: 'Get an overview of all webforms.'
  extended_help: Users with this permission can view the page [ABC]. They'll be able to see [XYZ], [ABC2], and [XYZ2]. So, you should only give this permission to users who need to see [ABC].

There would be the standard question mark in a circle image that users could mouse over to see the extended_help in a popup.

Is this issue actually in scope for Drupal CMS? Redesigning core UIs is not, to my knowledge, really in our wheelhouse.

The Drupal ideas queue might be a better place for this.

I think it is definitely a Drupal CMS issue. Core does not have a concept of a trial experience for evaluators and is geared to developers who know how to configure complex sets of permissions. It’s not for core because it’s not for everyone. It’s needed to be considered for the market of Drupal CMS.

An additional idea is to add sections. For instance, the 'Access any webform configuration' permission could go in an 'admin' section while 'Edit own submission' could go in a 'user' section. Sections would have weights and extended_help. Permissions would also have weights that would control their position within its section. 'section_callbacks' would be similar to 'permission_callbacks'; if both 'section_callbacks' and 'sections' are provided, then sections from the callback(s) are appended to 'sections'.

All of these changes would be optional so current *.permissions.yml files would continue to work, they'd just have one section and no extended_help.

If enough are interested I can make a patch for PermissionHandler::buildPermissionsYaml() to add these optional items to the return from PermissionHandler::getPermissions(). I'd probably use a helper object in buildPermissionsYaml() but the return value of getPermissions() would stay the same. Then, these changes could be worked into the UI.

main:
  extended_help: These permissions deal with the webform module. You can probably use the default settings, however, if you want to do [ABC], you might want to [XYZ]. Another possible use case is [ABC2]. In that case you'd [XYZ2].

section_callbacks:
  - Drupal\xyz\ABC::xyz
  - Drupal\xyz2\ABC::xyz2

sections:
  - name: admin
    weight: 1
    extended_help: something, something, and something
  - name: users
    weight: 2
    extended_help: another thing, another thing, another thing

'access webform overview':
  title: 'Access the webform overview page'
  section: 'admin'
  weight: 1
  description: 'Get an overview of all webforms.'
  extended_help: Users with this permission can view the page [ABC]. They'll be able to see [XYZ], [ABC2], and [XYZ2]. So, you should only give this permission to users who need to see [ABC].

I'm not against any of these suggestions, but changing the way the permissions system works is outside the scope of Drupal CMS. That is almost certainly a core patch, or at the very least some kind of shim module we could include. Either way it's not in our wheelhouse, so I sort of want to move this to another issue queue purely on the grounds that it's not the responsibility of Drupal CMS to implement.

@phenaproxima if we move this issue to core, how do we make sure the initiative doesn't lose sight of it? This issue is as much about UX as code and could span multiple core and contrib projects.

Well, that's the thing...I'm not sure which initiative it falls under. This probably calls for input from @tim.plunkett, @lauriii, or @pameeela.

Sounds good!

Since this requires changes to core, it doesn't seem totally appropriate to discuss here, since the Drupal CMS team can't make that call.

As a minimum, create a role for new evaluators and assign this role and the content editor role at install.

I don't really follow this; the person setting up the site is an admin be default, and I can't imagine we'd want to change this. But also this is suggesting adding a role to a role?

Drupal CMS should be thoughtful about what roles are included by default and there was a suggestion for this in the content publishing track. Whatever we do has to fit within what core currently offers, and redesigning that doesn't currently fall into any current Drupal CMS work tracks.

I've written code to parse the yml format I gave above and I'll release it as a contrib module within a week or so.

This does not necessarily require changes to core because the parser class I'm replacing (PermissionHandler) is a service (user.permissions) and, unless something's doing something it shouldn't, I should be able to override that. I'll duplicate the code to show the permissions page and replace that path.

Hopefully the core team will see the utility of a much less cryptic permissions page.

@pameeela I think that people are struggling to understand my description, which was written way back in June and we have moved on a long way since then.

For a single non-technical evaluator experiencing Drupal for the first time, the administrator role doesn’t make a lot of sense (to me at least) and I think we should re-imagine this because:

- The UI has a lot of complexity and will be off-putting to some people.
- The permissions system in particular doesn’t make a lot of sense in the context of an in browser trial experience - the evaluator can make changes to the permissions but if they have elevated privileges nothing will change in the UI for them.

For a trial experience, I think the areas of the UI that are available should be curated and the easiest way I could think to accomplish this was to assign a role that has a subset of the permissions, with some means to elevate the role.

An entirely different way to solve the same problem would be to make all areas of the UI intuitive and comprehensible to anybody of any level of experience that chances upon them.

To help illustrate why some sections of the UI are going to be problematic for our evaluators early on in their journey, this week a non-developer user with some knowledge of and experience with Drupal thought that a module was not installed because the toggle in the UI was grey rather than green. In fact it just could not be toggled because another module depended on it.

Indeed! We are going to focus on reimagining the entire 'Extend' section post v1 (we have already started this process with one of the designers who has been working on Drupal CMS). I totally agree these are existing issues, but I don't think that piecemeal solutions are the right answer. It could be that this change to the permissions is a good approach, but it feels like a shot in the dark at this point. I think part of how we've ended up here was by trying to solve specific UX problems in context, rather than considering why things are this way in the first place.

So right now, our next priority is 'Extend', but permissions is another area that could use improvement. In order to do this effectively, I think we should approach it with a proper UX process.

Of course, all contributors are welcome to work on solutions they believe in. I guess I would just caution that this feels somewhat hasty and potentially not the solution. As long as that's clear, then carry on!