Hello,

I would like to suggest that the "Role export and import" documentation be reworded silently for clarity.

The documentation can be found here: https://docs.moodle.org/37/en/Role_export_and_import

The title states "Role export and import".

The first section heading states "Export role definition to file" which speaks to exporting.

The next section heading is "Create new role (Import) from definition" which speaks to importing a NEW definition. 

But what about importing changes to an existing role definition (which is what I was looking for)? The documentation does not appear to mention that. If you try it through Moodle (just importing an export definition into Moodle for a default role) it throws an error. So it appears not to be possible and that the user has to eyeball the individual capability settings from one moodle and the other–comparing them line-by-line.

But it turns out the third and final section does indeed speak to how to do this. But it is entitled "Reset existing role to definition". "Resetting", to me, sounds like resetting a role back to the out-of-the-box Moodle settings after you have modified the default/existing roles.

I would like to suggest changing the following heading

"Reset existing role to definition"

to

"Import changes to existing role definition"

Additionally, I would suggest clearing up what the instructions in this third section state by changing this line

"To reset role: "

to

"To reset or change an existing role by importing a definition you exported elsewhere:"

This may sound picky to some but given the title of the page was about import/export and that neither verb is used for the third section it was very confusing to me. The slight change might help.