roles/roles: Create new page with info on roles in Mahara

This is the start of a section where role-specific
information can be gathered in a sort of overview.

manual-build @ 1c0093fb

-Subproject commit 8dad5047d8ab10b94ad1f6b79727076b0ae6646b
+Subproject commit 1c0093fb50f21eb287a33fbd37d8d3e1223065ee

source/index.rst

@@ -40,7 +40,7 @@ You can see the list of contributors to the manual on `Open Hub <https://www.ope
    /account/notifications
    /misc/fulltextsearch
    /administration/administration
-   /staff/staff
+   /roles/roles
    /external/externalapps
    /mahoodle/mahoodle
    /misc/mobile

source/roles/overview.rst

+.. include:: /shortcuts.rstext
+
+.. index::
+   pair: Roles; Overview
+
+.. _roles_overview:
+
+Overview
+-------------------
+
+Roles allow account holders to have different permissions throughout the site. Roles can either be set on an account to have certain permissions no matter the context or they can be set in the context of a group or portfolio access.
+
+The following is a compilation of all roles in Mahara when taking a setup into account that does not include :ref:`isolated institutions <isolated_institutions>`.
+
+Regular account
+~~~~~~~~~~~~~~~~~~~~
+
+When someone receives an account on Mahara, they can get started creating portfolios straight away. Depending on the site's configuration, they may already receive additional permissions automatically. The typical permissions are:
+
+* Create portfolios in own portfolio area.
+* Copy personal portfolios or those from others who permitted the copying of their portfolios.
+* Share personal portfolios with others, either groups of people or individuals.
+* Create groups if permitted by the site administrator.
+
+Site level
+~~~~~~~~~~~~~~~~~~~~
+
+There are two built-in roles on the site level:
+
+* site staff
+* site administrators
+
+Additional roles can be created by making hard-coded changes.
+
+Site staff
+^^^^^^^^^^^^^^^^^^^^^^
+
+The 'Site staff' role gives account holders the 'Staff' role across all institutions and not only in 'No institution'.
+
+They can:
+
+* view the real names of people and their usernames, not only their display name, no matter the personal preference of an account holder.
+* create of :ref:`controlled groups <group_types>`.
+* access the *People search* page in the administration and view members of all institutions.
+* view certain reports if the site administrator allows it in the :ref:`'Institution settings' <institution_settings>`.
+
+Site administrator
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The 'Site administrator' role is the most powerful one in Mahara. It should only be given to a small number of people. Typically, those giving support should operate with the least amount of privileges. That's why it is recommended that organisations set up at least one institution on Mahara (not counting the default 'No institution') in order to allow support staff certain administrator permissions but not far-reaching ones.
+
+Site administrators can basically access all areas of the configuration and administration of Mahara, no matter the institution.
+
+Per default, they do not automatically have access to other people's accounts, but still need to :ref:`masquerade as them <login_as>` as such logins can be tracked if desired.
+
+Institution level
+~~~~~~~~~~~~~~~~~~~~
+
+There are four built-in roles on the institution level:
+
+* Institution member
+* Institution staff
+* |new in Mahara 22.04| Institution support administrator
+* Institution administrator
+
+Institution member
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If a person is a member of one or more institutions, there are a few changes to make it easier for them to find people within their institution:
+
+* When :ref:`searching for other people <people>`, results are initially only presented from their own institution(s). They can still search for others though.
+* When sharing portfolios, a new option of sharing the portfolio with their entire institution is available.
+* When sharing a portfolio with a particular person, the selector lists members of their institution(s) first.
+
+Institution staff
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Institution staff have the same permissions as site staff, only restricted to the institution(s) in which they have the staff role.
+
+Staff permissions can be given manually or via SAML automatically, if the IdP contains that information.
+
+|new in Mahara 22.04| Institution support administrator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :ref:`'Institution support administrator' role <institution_support_admin>` contains all institution staff permissions and allows the support administrator to masquerade as another account holder if they are a regular institution member or institution staff in the institution for which they are the support administrator.
+
+People with this role cannot make changes to the institution settings, create or manage institution portfolios and other content.
+
+This role was created to allow organisations to give certain administrator privileges to first-level / hotline support staff without giving them full institution administration permissions.
+
+Institution administrator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An institution administrator has all permissions from the institution support administrator. In addition, they can:
+
+* Configure institution settings
+* Manage institution portfolios
+* Update :ref:`the institution's static pages <static_institution_pages>`.
+* Manage the legal statements that institution members may need to approve before they can use their account.
+
+Group level
+~~~~~~~~~~~~~~~~~~~~
+
+There are three built-in roles that can be given on the group level:
+
+* Group member
+* Group tutor
+* Group administrator
+
+Group member
+^^^^^^^^^^^^^^^^^^^^
+
+A group member is a regular account holder in a group that allows them to actively participate in group activities. If a group has editability dates set, group members cannot engage in collaborative activities outside of the given time frame.
+
+Group tutor
+^^^^^^^^^^^^^^^^^^^^
+
+The 'Group tutor' role only exists in course groups. They can view portfolio submissions, but not manage group members.
+
+Group administrator
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Group administrators can configure groups and have the highest level of privileges in them. If a group administrator also has the staff role, they can set up controlled groups.
+
+Portfolio access
+~~~~~~~~~~~~~~~~~~~~
+
+Certain portfolio assessment functionalities required that the permissions around portfolio accessed are made more flexible to account for more granular ways of engaging with certain portfolio content. These additional roles that are given to individuals when they receive access to a portfolio are:
+
+* Manager
+* Peer assessor
+* Peer assessor and manager
+* Reviewer
+
+Manager
+^^^^^^^^^^^^^^^^^^
+
+The 'Manager' role is only valid within the context of the :ref:`'Sign-off' block <sign-off_block>`. It allows a person with this role to verify individual portfolio pages.
+
+Peer assessor
+^^^^^^^^^^^^^^^^^^^^
+
+The 'Peer assessor' role is given to people who shall be able to provide :ref:`peer assessments <peer_assessment_block>` on a portfolio. Depending on the institution settings, peers may or may not see the content of the rest of the portfolio.
+
+Peer assessor and manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This combined role allows people to both make peer assessments as well as verify portfolios as managers.
+
+Reviewer
+^^^^^^^^^^^^^^
+
+This optional role can be given to people who shall interact with a :ref:`'Portfolio review' block <portfolio_review_block>` on a portfolio completion page. By giving this role to an individual, others can still have regular access to a portfolio, but are not able to give it an overall review.

source/roles/roles.rst

+.. include:: /shortcuts.rstext
+
+.. index:: Roles
+
+.. _roles:
+
+Roles
+==============
+
+There are many roles in Mahara in various contexts that serve particular purposes.
+
+.. toctree::
+   :maxdepth: 2
+
+   /roles/overview
+   /roles/staff