User talk:Olli Savolainen/Suggestion to develop Roles popup help text

From MoodleDocs

Slightly different start

This is for help pop up, keep it simple:)

Roles overview

Roles are Moodle's way of determining what a user can do in a situation. Roles help decide who does what, where.

There are two key concepts that help in understanding Roles: Context and Permission. A more advanced related topic concerns Overrides, which are exceptions.

Context can be thought of as the place a user is at, "the where".

A Permission helps define an action, what the user can do. Simply put a permission will allow or not allow an action by a user. Each permission can be passed along from context to context and not change for a user.

Roles are an easy way of assigning many specific permissions to many specific users at once.

Context and permissions, allows a user to be a teacher in one course and a student in another. Or allows one user in a Teacher role to delete forum posts and Student to create forum entries. Or to make an exception for a student in a course to have the permissions of a teacher in a specific forum.

Thanks Chris. It seems indeed that your version starts simpler than mine, though I guess the examples would be helpful a bit more verbose.
At the end of your text, the second to last paragrap (note: Chris removed it so if you are now reading this conversation for the first time you will have to take a look at the history to see it), it seems to me though that you are trying to take it back to the system-style talk, which I was trying to fix in the first place. It talks in the language of the Roles conceptual system, and it takes someone who already understands that system to understand those sentences in the first place. --Olli Savolainen 13:02, 7 August 2009 (UTC)
I agree. There is a different style for writing for help and I have not really developed it. I learn by doing and eventually I will walk through the door :) --chris collman 15:16, 7 August 2009 (UTC)
I like the idea of learning together (especially when I get to be the one is RIGHT ;)) No, just kidding, but I seriously think we should more and more promote the idea of learning together and not being afraid of learning by doing before knowing the right way of doing something, so that is great. I'll try to see what are the benefits of both writings. --Olli Savolainen 16:11, 7 August 2009 (UTC)


Help styles and MoodleDoc styles

You hit upon a key point in your correction/suggestion. "It takes someone who already understands that system to understand those sentences in the first place."

IMHO, the purpose of help is really to give hints. If you don't understand the hint, then you want a link(s) to learn more. It is not really the place for verbose teaching examples. "For example" is probably not appropriate most of the time. In theory, hints should be a single instructional point in a lesson, not the entire lesson and certainly not a course in how to :) It is hard to break the habit of stringing Instructional Points together that I consider more a MoodleDoc style.

I also think help screens in English, really need to focus upon non-native-geek speakers of English. This focus also helps keep things simple and clear for the Geeks who are looking for "the hint, not a lecture". Probably not the best place to make these comments, feel free to erase them. --chris collman 17:07, 7 August 2009 (UTC)

Roles

Not sure if this is in help, or is the addition to the/a MoodleDoc page.--chris collman 17:09, 7 August 2009 (UTC)

Generally speaking, people are assigned a specific role on a Moodle site. A Moodle Role is a set of defined permissions, appropriate for a group of users who perform the same kind of tasks. Typical roles might be student, teacher, or administrator.

Example: Jim wants to enroll as a student in the course English Literature I. Moodle needs to allow him to View a course and Post to forum but not allow him to Modify a course setting. This is expressed in Moodle as: The user Jim should be assigned the role of Student in the (context of the) course English Literature I.

Example 2: Eva is an experienced secondary school teacher on your Moodle site but is assisting in a graduate level course for the first time. You may have a Role called "New Teacher" that is set up to allow a user to grade papers but not view or change the gradebook, or delete forum posts. We might say: The user Eva is assigned as a teacher in the (context of) secondary school courses and be assigned as a "New Teacher" in the (context of the) graduate level course.

A more advanced feature is that Roles can be assigned to users just for a given Context. More information: Assigning roles

Moodle allows you to also define your own roles, so, for example, you can give a group of students more responsibility than others.

Explaining Roles

Here is the example I use when explaining roles to Moodle Administrator Training delegates. This training usually takes place at their school...

"To get into this school I've had to sign in: I'm an "authenticated user" of this school. That's my role when I am wondering around the school's corridors (it's a very limited role). I can't simply wonder into any room and start teaching. That is until I come into this room, where in this context I am the trainer. That gives me certain extra capabilities that I don't have in the rest of the school (e.g. I can use the computer on the desk, I can write on the interactive white board, &c.). In Moodle that's just like having the role of Teacher in the Moodle course context. If you are a teacher in your classroom somewhere else in the school then you have the same capabilities as I have in this room. But when you are in this room you are now the student. You've got a different set of capabilities in this room - where you are now a student - to those that you have in your classroom - where you are then teacher. That's just how it is in Moodle. You can be a teacher on one course but a student in another. Different roles in different contexts".

Another example of having different roles in different contexts is that you can be a teacher during the day but be a student in evening classes at night. It's still you but you have different capabilities in those two different contexts.

I can then talk about the capabilities you have in different contexts and not have to talk about permissions at all.

One of the big problems I have when training teachers is that they confuse their job title, i.e. "teacher", with the role of "teacher" - which is limited to specific contexts. Just because they are a teacher they can't wonder into any school and start teaching.