Moodle community sites

Moodle documentation: Roles popup documentation

 
This discussion has been locked because a year has elapsed since the last post. Please start a new discussion topic.
Picture of Olli Savolainen
Moodle documentation: Roles popup documentation
Group Core developers
Among other things, I have bent my head around the roles system this summer, and thought we can do better than the current Roles help popups, which seem to be written from the point of view of the system and not that of the user.

So I rewrote the Roles text and named it Roles overview, and moved some of the text that used to be there to a new page.

I tried to bridge the needs of the users to the language of the system a bit and put it in the docs:

Suggestion to develop Roles popup help text

Please do comment, and modify the wikipage as needed. Even though it is in my userspace I do not mind it being edited at all. smile The names of the permissions are probably just wrong so suggestions are welcome. There may also be outright mistakes, since I am learning this myself and trying to imagine how I would learn it easily.
 
Average of ratings: -
Ray Lawrence
Re: Moodle documentation: Roles popup documentation
Group Particularly helpful Moodlers
Hi Olli,

I started to read this but stopped after "you need to understand two key concepts".

I think you need to include Capabilities as a key concept too.
 
Average of ratings: -
Picture of Olli Savolainen
Re: Moodle documentation: Roles popup documentation
Group Core developers
Hm, capabilities is not there in the current popup documentation either, so I missed it.

I am not sure if adding capabilities to the soup adds in mastering the usage of Roles, since the concept is so close to a permission. Why do you think it is needed?
 
Average of ratings: -
Picture of Olli Savolainen
Re: Moodle documentation: Roles popup documentation
Group Core developers
Actually, the concepts seem so close to each other that now that I read the definition of a capability, it seems I may be Saying permission when I mean capability.

However, I am still not convinced why the user would need both of these concepts in managing their roles, the division seems artificial.

That's just my impression so far, of course.
 
Average of ratings: -
Ray Lawrence
Re: Moodle documentation: Roles popup documentation
Group Particularly helpful Moodlers
A Capability is something that could be done.
A Permission is whether you are allowed to do it.

Each role is a combination of one or more capabilities and permissions. Either is redundant without the other.
 
Average of ratings: -
Me
Re: Moodle documentation: Roles popup documentation
Group Plugin developers
Hi Ray and Olli,

I know what Olli means... with the best will in the world the words "capability" and "permission" seem to be used inconsistently. Unless I can be corrected I'm not entirely sure there is the concept of permissions in Moodle. You have a role in a specific context. Even if you override a role's capabilities in a specific context you are simply changing that role's capabilities in that context - you aren't changing what that role is permitted to do: you are changing its capabilities.

If we are treating roles as "objects" in the philosophical sense (which seems to be the intention) then objects are defined by their state, behaviour and their identity. Change any one of those then you have a different object, essentially. If this is indeed the intention then it's all to do with capabilities. Philosophically, certainly in OOP, permissions don't come in to it...

...as far as I can see smile

Hope this makes sense (Ian strains brain back to when he studied OOP)

Ian.
 
Average of ratings: Useful (1)
Picture of Olli Savolainen
Re: Moodle documentation: Roles popup documentation
Group Core developers
Thanks Ian,

I had to take a nap and read you text again to understand it, and to the degree I understand its connection to what I said, you seem to be expressing the same thing in different terms. I was kind of hoping there would be a solution to what concepts would actually be helpful in explaining the functionality to the user.

A Capability is something that could be done.
A Permission is whether you are allowed to do it.

Ray, what I was trying to ask was: why don't we just have Capabilities, and then express permissions implicitly. The way of using the word Permission you suggest goes against my understanding of how the word is used in English, and my brain twists!

You can say "I have a permission to do this", or even "I have a permission to use this capability". I understand (though only barely) if someone says For the Role of a Teacher, the capability of changing the short name of a course is allowed/prevented/prohibited/inherited. I have lots of difficulties when someone comes to tell me that

The Permission of the Capability to change the short name of a course for the role of a teacher is allow.

This is how you would use it, right?

Even if it was

The Permission to change the short name of a course for the role of a teacher is allow.

It would still confuse someone just learning the concepts, "Wait a minute, you were just talking about capabilities, and now you're saying it's a permission?!".

The concept of a permission, then, seems just a shorthand for what is set for a particular capability in a given role. It is not a concept of its own, it is an extraneous shorthand with lots of redundance with the concept of a capability, and it seems much easier to just spell out what you are actually saying instead of using it.

For me, the way Capability is used in the Roles system is in sync with how the word is used in English, but the way Permission is used and what it means is different and contradictory with what it means in English. A permission is no kind of a setting or a value, it is a permission. The value for a capability in a role may consequently lead in me being capable of doing it, but the value is not a permission. If it were a permission, the value could only be allow, since otherwise it is prohibition or prevention.

I have strong wiring in my brain for what the word permission means, so every time I see the Moodle concept permission, I first have to try to unlearn the actual english concept, and it will always be difficult since it is very hard wired to my brain and I am unmotivated to learn the Moodle concept instead since the actual English expression is more useful to me in real life. So if you really want to have a separate concept for this shorthand, please call it Xigrenzedf or Herwondit, so it will not confuse my brain ;).

Chris simplified my writing in the talk page of my suggestion.
I am not quite sure what to make of it yet.

 
Average of ratings: -
Me
Re: Moodle documentation: Roles popup documentation
Group Plugin developers
Hi Olli,

I had to take a nap and read you text again to understand it, and to the degree I understand its connection to what I said, you seem to be expressing the same thing in different terms.

That's right - I was smile. When I'm teacher or administrator training the topic of roles is the one that causes the greatest confusion. In order to construct the correct "mental model" I don't use the term permission at all. It just confuses people. I talk about the concept of capabilities and explain that you can turn them on and off in different contexts - and that's all I need to say in order for teachers and admins to manage roles in their Moodle. I haven't found a sensible way of training Moodle users on roles using both the words "capability" and "permission" without having a long (and ultimately pointless) debate on what the differences are between a capability and a permission.

A permission is no kind of a setting or a value, it is a permission.

Agreed. My youngest son has just learned to ride a bike. It's not that he had the capability but didn't have permission - he simply didn't have the capability. If you're a course creator you can't delete courses (by default). It's not that you have the capability but don't have permission: you simply don't have the capability. That (to me) is the same as my son's bike-riding capability.

When I'm training I use a real-world example of roles in a school. I've added a couple of examples I use to the talk page of your suggestion. To be honest (and no offence to anyone) I don't find the examples of how roles work in Moodle in the Moodle docs to be very helpful.

Hope this helps,

Ian.
 
Average of ratings: Useful (1)
Mary Cooch
Re: Moodle documentation: Roles popup documentation
Group Documentation writersGroup Moodle Course Creator Certificate holdersGroup Moodle HQGroup Particularly helpful MoodlersGroup TestersGroup Translators
I've been following this thread with great interest - although I deal with roles/permissions/capabilities myself and (usually) seem to get by I've never thought through the semantics until now - I just wanted to butt in to say a) I agree wholeheartedly with Ian and b) I also think those examples given on the talk page
are really clear smile

 
Average of ratings: -
Picture of Olli Savolainen
Re: Moodle documentation: Roles popup documentation
Group Core developers
Hm, so should we try to get rid of the term Permission in documentation altogether? How would that happen? How about the UI? Are there situations where the concept of a Permission could be replaced with the concept of a Capability? Are there UIs where it could not?
 
Average of ratings: -
Me
Re: Moodle documentation: Roles popup documentation
Group Plugin developers
Hi Olli,

I'm not sure about changes to the documentation because I don't really get involved with that side of things. Certainly I can't think of a situation in the UI that needs the concept of a permission.

...but I'm willing to be proved wrong smile

Ian.
 
Average of ratings: -
Ray Lawrence
Re: Moodle documentation: Roles popup documentation
Group Particularly helpful Moodlers
I'm not sure that one is changing the capability. If I have permission to post to a forum or not the "thing that can be done" i.e. post to a forum does not change.

Perhaps the word "Capability" is the issue here as it has a number of potential connotations. I'm a veteran of saying "there has to be a better word for xyz" and then not being able to come up with a better alternative. "Action", "Task"?

Perhaps I'm too close to this but, having got my head around it with the release of 1.7, I've explained how the roles system works countless times to a successful conclusion. In my experience one needs to explain the following concepts (backed by examples, of course) without them all there is a gap in the learner's comprehension (because there is a piece missing.

Capabilities
Permissions
Contexts

Other may use different approaches and there are undoubtedly many ways to approach the topic but this works for me.


 
Average of ratings: -
Me
Re: Moodle documentation: Roles popup documentation
Group Plugin developers
Hi Ray,

I'm not sure that one is changing the capability. If I have permission to post to a forum or not the "thing that can be done" i.e. post to a forum does not change.

I understand what you mean. In the cognitive sense I find it better to build a suitable mental model in my delegate's heads by saying something along the lines of "As an admin I give or take away the capability to perform a certain function".

Perhaps the word "Capability" is the issue here...

You're probably right: I wouldn't mind if we were talking about permissions or capabilities... but I think the fact we are talking about both is what's causing the confusion. What do you think?

Do you think it would be better to talk about "a big long list of capabilities" and then talk about "giving roles permission to carry out a function", e.g. everyone in the school has the capability to be milk monitor ( those were the days wink ) but it's only certain children who have permission?

When I've tried this approach the usual response is that not all children have the capability smile This may be the seat of the argument about "capabilities" and "permissions".

I'm also wondering if this problem with semantics is just in English. Would other languages have this problem?

Hope this helps and cheers,

Ian.

 
Average of ratings: Useful (1)