diff --git a/src/doc/permissions.rst b/src/doc/permissions.rst
index 15091f8c16ec9737f744ca5b6d197421503ad08d..7a5cb15f3f1e36e534e2af9bccd3e8818ba2f0c9 100644
--- a/src/doc/permissions.rst
+++ b/src/doc/permissions.rst
@@ -36,6 +36,19 @@ A Permission Rule consists of:
    priority = ``true`` override those without, see the calculation rules
    below.
 
+There are two complementing types of permission rules that will be explained
+below: transaction permissions and entity permissions.
+
+.. _transaction-permissions:
+
+Transaction permissions
+***********************
+
+.. _entity-permissions:
+
+Entity permissions
+******************
+
 .. _Calculation:
 
 Permission calculation
@@ -93,13 +106,28 @@ used for administration users and in no other case. So, ...
 How to set permissions
 ----------------------
 
+There are multiple ways to set transaction and entity permissions. The most
+common and best tested way currently is to set global default entity permissions
+in the ``global_entity_permissions.xml`` config file, and role-based transaction
+permissions with the ``caosdb_admin.py`` `utility script
+<https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/src/caosdb/utils/caosdb_admin.py>`__
+of CaosDB's Python library which is also used to `manage users and
+roles <https://docs.indiscale.com/caosdb-pylib/administration.html>`__. Below you
+find a more detailed description of the possible ways of setting permissions.
+
 -  **Config file:** Some default permissions are typically set in the
    ``global_entity_permissions.xml`` file, see also the `default file
    <https://gitlab.com/caosdb/caosdb-server/-/blob/main/conf/core/global_entity_permissions.xml>`__. Here,
-   you can set the default permissions that every entity on the server has. Note
-   that you can add more rules but you can never remove rules set in the
+   you can set the default permissions that every entity on the server has. The
+   global default permissions can **only** be set in this file; all other ways
+   below can only change the permissions of individual entities. Note that you
+   can add more rules but you can never remove rules set in the
    ``global_entity_permissions.xml``. Thus, it might not be possible to overrule
-   permissions defined here (see :ref:`Permission calculation<Calculation>`).
+   permissions defined here (see :ref:`Permission
+   calculation<Calculation>`). Note also that, as the name suggests, only
+   :ref:`entity permissions<entity-permissions>` can be set this way. The
+   role-based :ref:`transaction-permissions<transaction-permissions>` have to be
+   set with one of the other ways explained below.
 -  **API:** Both REST and GRPC API allow to set the permissions. This hasn't been
    documented properly yet, but for the GRPC API, `the specification
    <https://gitlab.com/caosdb/caosdb-proto/-/blob/main/proto/caosdb/acm/v1alpha1/main.proto>`__