Urgent: Missing role and capability documentations

The new role and capability system ist a mighty step for moodle and was a lot of hard work.
We have a lot of discussions with users to understand the new systems and there are a lot of topics that are not easy to understand. The documentation under docs.moodle.org contains only 10 % perecentof the informations we need.

In the moment we say to our customers to wait for some weeks before they update, because we are also not shure if we understood all the settings correct.

Some topics and in some ideas for a better documentation:

• In which topics are changes in the settings, rights on default roles in comparison to ver. 1.6? (i.e. admin/coursecreator is automatically a teacher in the course he/she creates)
• What are the changes I have to do that 1.7 works in the same manner like 1.6 with the well known default roles? And what can't be changed?
• Write practical examples of creating new roles based on existing roles?
• Write practical examples of the use of roles in contextes? I.e. what happens if an existing role (teacher) is used context site/category/subcategory/course/different activity).
• Did we need a new role to give students access to the settings of a forum? Or can we give him the existing teacher role in this context?
• Practice for describing and administration of roles in organizational contexts.

This are only a few points from the discussions we had in the last days with users in the german forum, via mail and by phone.

And a translation problem: The setting forum:nothrottling isn't clear. Does it mean the same like 'thresholding' the postings. If yes, why did you use an otherwording, if not, what is the difference?

The contexts of the roles and capability system are such a complex work that it seams to be the best and fastest way that on of the core designer starts to document the main topics from an admins view Helen or other native speaker can add more informations in the next steps..

In the moment is the problem that lots of informations in handling the system are based on try-and-error testing of users.

Ralf