add role update docs, minor changes (#1689)

docs_manual/source/index.rst

@@ -52,9 +52,9 @@ Table of Contents
     ui_api_tokens
     ui_user_profile
     ui_project_overview
-    ui_project_timeline
     ui_project_members
     ui_project_update
+    ui_project_timeline
     ui_alerts
 
 .. toctree::

docs_manual/source/ui_project_members.rst

@@ -10,34 +10,66 @@ through this view.
 
 .. figure:: _static/sodar_ui/project_members.png
     :align: center
-    :scale: 50%
+    :scale: 60%
 
     Project members view
 
 
 Member Roles
 ============
 
-In SODAR, a single *role* at a time can be assigned to a user within a project.
-The following types of roles are available:
+In SODAR, a single *role* at a time can be assigned to a user within a category
+or a project. Role assignment works similarly between categories and projects
+except for special cases we will be detailed. With the exception of these
+special cases, "project" will be used to refer to either a category or a
+project.
+
+The following types of roles are available, ordered by descending
+level of rights and functionality within each project:
 
 Project Owner
-    Full access to project, with the ability to assign roles including delegates
-    and transferring ownership to another user.
+    Full access to project data and functionality. Ability to assign roles,
+    including delegates. Can transfer ownership to another user.
 Project Delegate
-    Full access to project with the exception of modifying owner or delegate
-    roles. This role is assigned by a project owner.
+    Full access to project data and functionality, with the exception of
+    modifying owner or delegate roles. This role can only be assigned by a
+    project owner.
 Project Contributor
-    User with access to create and modify data within a project, e.g. uploading
-    files and editing sample sheets, with some limitations. For example,
-    modifying project meta data or user roles is not allowed.
+    User with access to create and modify data within a project. This includes
+    e.g. uploading files and editing sample sheets, with some limitations. For
+    example, modifying project metadata or user roles is not allowed.
 Project Guest
     Read-only access to project data.
+Project Finder
+    A role assignable only to users in categories. A user with a finder role can
+    see child categories and projects along with their member lists without
+    gaining access to project data or project apps. This is usable for e.g.
+    members of staff in the organization maintaining the SODAR instance or a
+    specific category structure. This role allows them to see which categories
+    and projects exists and who manages them, in order to have a full picture of
+    the category and project structure. Actual project access can then be
+    requested from a project owner or delegate.
+
+
+Role Inheritance
+================
+
+Roles are inherited from parent categories. A role inherited from a parent
+category can be promoted for the current category or project. The promoted role
+is then also inherited by child projects in case of a category. Demoting
+inherited roles is not allowed. Inherited roles are marked in the member list
+with a downwards arrow along with a link to the category from which the role is
+inherited.
+
+Each project must have exactly one "local" (or non-inherited) owner. The amount
+of allowed delegates is set by the server administrators. The number of
+inherited owners and delegates are not limited. For contributors and guests, the
+amount per project or category is not limited.
+
+.. figure:: _static/sodar_ui/project_members_inherit.png
+    :align: center
 
-Project owner roles are inherited from parent categories. One owner is allowed
-per project, with the exception of inherited owners. The amount of allowed
-delegates is set by the server administrators. For contributors and guests,
-the amount per project is not limited.
+    Inherited member role
 
 
 Adding Members
@@ -57,17 +89,17 @@ You are presented with a form to select a user and a role for them. The user
 field works as a search box, where you can start typing a person's name or email
 address and available options will be presented as you type. If the user is not
 yet a SODAR user, you can also type an email address and be redirected to the
-separate invitation form.
+member invitation form.
 
 .. figure:: _static/sodar_ui/project_members_add.png
     :align: center
     :scale: 65%
 
     Member adding form
 
-If email is enabled on the SODAR server, an email notification is sent to the
-user being added into the project. You can preview this email by clicking the
-:guilabel:`Preview` button. To assign the role, click the :guilabel:`Add`
+If email sending is enabled on the SODAR server, an email notification is sent
+to the user being added into the project. You can preview this email by clicking
+the :guilabel:`Preview` button. To assign the role, click the :guilabel:`Add`
 button.
 
 
@@ -85,6 +117,20 @@ the membership from a user, you can click :guilabel:`Remove Member`.
 
     Member update dropdown
 
+In case of an inherited member, you can see the :guilabel:`Promote Member`
+option instead of the regular updating link. As described before, inherited
+members can only be promoted to a higher role. The link opens a form similar to
+user updating, only allowing you to select a role of higher rank than the
+current inherited one. If you wish to demote an inherited user or remove their
+access entirely, you should follow the inherited category link in the member
+list and remove the role from a parent category.
+
+.. figure:: _static/sodar_ui/project_members_promote.png
+    :align: center
+    :scale: 80%
+
+    Member promote dropdown
+
 Modifying the project owner works slightly differently. In the dropdown next to
 the owner in the member list, you will see a :guilabel:`Transfer Ownership`
 option. This will present you a form where you can select a new owner from the
@@ -99,7 +145,7 @@ functionality is only available for users currently set as the project owner.
 
 These dropdowns also contain a :guilabel:`History` link, which will take you to
 the :ref:`Timeline <ui_project_timeline>` application to view the history of the
-user's membership(s) in this project.
+user's membership in this project.
 
 
 Inviting Members

docs_manual/source/ui_project_overview.rst

@@ -7,9 +7,9 @@ Once you navigate into a project, you can see the project overview on the right
 hand side of the screen. The sidebar on the left hand side has been expanded to
 display links related to the project.
 
-Furthermore, you can see a navigation breadcrumb for quickly returning to a
-parent category, as well as the project title bar displaying the project title,
-description and some general links.
+Below the site title bar there is a navigation breadcrumb. It can be used to
+easily return to a parent category. Te project title bar displays the project
+title, description and project-specific links.
 
 .. figure:: _static/sodar_ui/project_detail.png
     :align: center