Improve the wording of required rights

[MichaelHamann]

Hi everyone,

while I’m quite happy that since XWiki 17.4.0, there is a UI for setting the required rights of a page, unfortunately it turns out that users or even other developers don’t understand the wording in the UI. As a minimum requirement for an improved version, users should be able to understand that a page that enforces a right is a page containing scripts even without fully understanding required rights. I’ve created a design page to document the current wording, from what I consider the most important to improve to the least important.

I would like to invite everybody to contribute ideas how to improve the wording, either here in this thread or directly on the design page (by adding sections with the improved wording in the respective section). I’ll try collecting everything from this forum thread in the design page (any help with that is of course also welcome). As a second step, we’ll then ask people who haven’t been involved in this discussion how/if they understand the different proposed formulations. Of course, you can also express your support for certain formulations in this forum thread. Depending on the result, I might open another proposal to decide which formulation we use in the end.

Thank you very much for your contributions!

PS: I’m not contributing any formulations for now, you can consider the current status as my proposal as these texts were mostly written by me.

[paulinebessoles]

Hi @MichaelHamann, thank you for creating the design page with the wording!

I added a section with proposed improvements, please tell me what you think about it.
In general, I think we should:

1. Consider replacing “rights” with “permissions” (applicable to all XWiki access rights, could need its own proposal, but I think that it should be discussed more broadly with a global revamping of user management and rights management)
2. Replace “enforce” by a word more user-friendly, like “apply” or “protect”

[vmassol]

@paulinebessoles

Consider replacing “rights” with “permissions”

Doing this would cause confusion and inconsistencies. We use Rights in the doc on xwiki.org, in the code, and in the UI of XWiki.

Just to give one example:

So -1 from me FTM. I also don’t see any explanation why Permissions would be better than Rights. As you said, if we want to change to Permissions we’ll need a specific proposal and it’s a large amount of work. What’s sure is that we need full consistency in the UI.

Thx!

[paulinebessoles]

@vmassol

What’s sure is that we need full consistency in the UI.

Completely agree, and yes this change should be made only if we make it everywhere.

From what I saw in other tools, permissions and roles are more commonly used than rights, but indeed it’s not the place to discuss it, I’ll suggest it when we discuss the revamp of Rights.

@vmassol

We use Rights in the doc on xwiki.org

On another note, I don’t think that the fact something is documented in the documentation is a valid argument to not do wording improvements in the UI.

@paulinebessoles

I added a section with proposed improvements, please tell me what you think about it.

I updated my wording proposals to switch back to “rights”.

[vmassol]

@paulinebessoles

On another note, I don’t think that the fact something is documented in the documentation is a valid argument to not do wording improvements in the UI.

No, but my point was that it would need to be changed everywhere in the doc too.

[MichaelHamann]

I’m mostly okay with the proposed changes, thank you very much! There is just one translation that I believe is very misleading:

To edit this page and run its content, users need to have at least this right:

It’s not true that users need to have any rights to run the content of the page, what this sentence should say is that the content runs with this right. So for example, a script macro in a page with script right runs with script right while if the page had programming right, the script macro runs with programming right (and can execute dangerous code that requires programming right).

What about:

The content of this page runs with the following right, users need to have this right for editing it:

I’m also not super happy about the descriptions of the rights, as they might simplify a bit too much:

Scripting: Allows running script macros.
Administrating the wiki: Allows making administrative changes at the wiki level.
Programming: Allows advanced scripts with full access to the wiki.

Script right is not only about script macros, it’s also about Velocity scripts in the page title or JavaScript or CSS skin extensions on the current page. “Administrating the wiki” is quite broad, so this is maybe okay, though it’s not clear to me if it is clear that this is the right for a wiki macro that can be used on the current wiki or a UI extension. Programming right gives access to the whole farm, not just the wiki, maybe we could make this clearer?

Apart from that, I think some translations need to be improved for consistency: Several translations mention “Review the required rights” because the old label of the button was “Review required rights” but now it is “Check page rights” so they should be adjusted to “Check the page rights” I think.

[paulinebessoles]

Thank you for your feedback Michael!

I implemented your proposed changes, as well as the feedback from Anca, you can check the modifications here.

[paulinebessoles]

Here is a summarization of the feedback provided by @lucaa

1. Confusing wording about execution rights in the dialog

The sentence:

“Scripts and objects execute only with the selected rights.”

is unclear and misleading.

In XWiki, scripts and special objects always execute with the rights of the last author who edited the page. There are no “free-floating” rights used for execution, unless this is meant to describe the behavior introduced by required rights.

When required rights are not enforced, it’s clear whose rights are used (the last editor). When they are enforced, the text no longer mentions any user, which makes it feel like two incomparable situations.

The existing documentation is also confusing, especially this sentence:

“Denying script, wiki admin, or programming right when it is not explicitly granted.”

Here, “granted” should actually be “required”.

Current	Suggested	Implementation in the design proposal
“Scripts and objects run using the rights of the last person who edited the page.”	“Scripts and objects are executed with all the rights of the last person who edited the page.”	Yes
“Scripts and objects execute only with the selected rights.”	“Scripts and objects are executed with the rights of the last author who edited the page, but only those rights which are explicitly required, even if the author has more rights.”	Yes, rephrased
“Only users with ‘Edit’ right and the selected rights can edit the page.”	“Only users with the ‘Edit’ right and the explicitly selected rights can edit the page.”	Yes, rephrased

2. Lack of consistency in the “Information about the current required rights” section

In the section
#InformationAbouttheCurrentRequiredRights, the explanations for the three cases are inconsistent. Ideally, all three should answer the same set of questions, but currently they don’t.

• Case 1
  “No rights are currently required on this page. It runs using the rights of the last person who edited it.”

  This answers:

  • Which rights are marked as required

  • Which rights are used to execute the page

  But it’s unclear whether required rights are enforced or not.

• Case 2
  “Required rights are enabled for this page, but none are defined. Only the standard ‘Edit’ right is needed on this page, and no special rights apply to its content.”

  This answers:

  • Whether required rights are enforced

  • Which rights are marked as required

  But it also introduces new concepts that weren’t mentioned before:

  • “Which right is needed for the page”

  • “Which rights apply to the content”

• Case 3
  “To edit this page and run its content, users need to have at least this right:”

  Suddenly, this talks about who can edit the page — a concern that wasn’t addressed at all in the previous two cases.

Suggested improvement

For each case, the text should clearly and consistently answer the same core concerns, such as:

• Are required rights enforced on this page?

• Which rights are required?

• Which rights are used to execute the page content?

• Who is allowed to edit the page?

This doesn’t need to be presented as bullet points, but the wording should make sure all these concerns are clearly addressed in every case.