From 0aad6325ee77446848fc6502420a34a03737a491 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcin=20S=C4=85gol?= Date: Thu, 29 Feb 2024 13:30:37 +0100 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Sarah McCarthy --- .../ExampleConfiguration/Index.rst | 60 +++++++++---------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/Documentation/PermissionsManagement/ExampleConfiguration/Index.rst b/Documentation/PermissionsManagement/ExampleConfiguration/Index.rst index 0a3881fc..9d1bf773 100644 --- a/Documentation/PermissionsManagement/ExampleConfiguration/Index.rst +++ b/Documentation/PermissionsManagement/ExampleConfiguration/Index.rst @@ -8,38 +8,38 @@ Example configuration of backend user groups ============================================ -Knowing how backend user groups can be :ref:`categorized <_available-acl-options>`, -and how they can be organized using :ref:`naming conventions <_naming-convention>` -to distinguish their purpose or context, also following other best practices, -more advanced examples of group structures for projects with a single or multisite setup -can be discussed. +How backend user groups can be :ref:`categorized <_available-acl-options>`, +and organized using :ref:`naming conventions <_naming-convention>` +to distinguish their purpose or context as well as following best practice +and more advanced examples of group structures for projects with a single or multisite setup +are discussed. .. _single-site-structure: Backend groups’ structure for a small project ============================================== -When setting up backend groups and permissions for small, single-site projects, -consider future complexity. Organizing groups by best practices from the start +When setting up backend groups and permissions for small, single-site projects +future complexity should be considered. Organizing groups by best practice from the start makes future extension and maintenance easier. Consider a scenario where two role groups are required: one for general content management, -named :samp:`Content Editor`, and another for survey management, named :samp:`Survey Manager`. +named :samp:`Content Editor`, and one for survey management, named :samp:`Survey Manager`. The following conditions should be met: * Both roles should manage content in all languages * Both roles should perform any file operations -* The Content Editor role has a dedicated file mount for organizing various files +* The Content Editor role has a dedicated file mount for organizing files * The Survey Manager role should have access to a dedicated file mount within the same file storage * The Content Editor role should be able to view files uploaded by users with the Survey Manager role, as they might need them for blog posts mentioning the surveys * The Content Editor role should manage all types of content, except for surveys * The Content Editor should have access to a dedicated branch in system categories -* The Survey Manager role should only see the storage folder and a selected part of the pages tree where the surveys are listed and rendered +* The Survey Manager role should only see the storage folder and the part of the pages tree where the surveys are listed and rendered * The Survey Manager role does not need access to any system categories With these requirements in mind, the backend groups structure can be planned. -Following the recommendations of having the :ref:`System Groups <_system-groups>` +Following best practice of having :ref:`System Groups <_system-groups>` and :ref:`Access Control List Groups <_acl-groups>`, it could look like this: .. uml:: _backend-groups-simple-project.plantuml @@ -48,35 +48,35 @@ and :ref:`Access Control List Groups <_acl-groups>`, it could look like this: Having defined all the required :samp:`System` and :samp:`Access Control List` groups, they can be combined to fulfill the :samp:`Content Editor` and :samp:`Survey Manager` -roles requirements. +role requirements. .. uml:: _backend-groups-simple-project-organized.plantuml :align: center :width: 700 -Both :samp:`System` and :samp:`Access Control List (ACL)` groups serve as components +The :samp:`System` and :samp:`Access Control List (ACL)` groups serve as components that can be integrated into a larger entity, in this case, the role group. These role groups can then be assigned to users. As previously mentioned, -it's recommended that only the role groups be directly assigned to users. +permissions should only be assigned to users via role groups. .. _multisite-structure: -Backend groups’ structure for a multi-site project +Backend group structure for a multi-site project ================================================== -When designing backend user groups for a multi-site project, the approach remains -consistent with that of a smaller, :ref:`single-site project <_single-site-structure>`. -Adhering to recommended best practices from the start simplifies the expansion -and preparation of a more advanced setup. +When creating backend user groups for a multi-site project, the approach is +the same as that of smaller, :ref:`single-site projects <_single-site-structure>`. +Adhering to recommended best practice from the start simplifies building the website +and prepares for a more advanced setup. This scenario describes a project with three separate sites (a multi-site setup). There will be three distinct :samp:`Content Editors` roles, one for each site, -along with multiple other roles that will have cross-site access and permissions +along with other roles that will have cross-site access and permissions to manage content. -Rhe following condition should be met: +The following conditions should be met: -* Project has 3 separate sites defined: Website A, Website B, Website C +* Project has 3 separate sites: Website A, Website B, Website C * Project has one default language and one translation to English language * For each site there are separate Content Editor roles as they will have different permissions * Content Editor roles on Website A and Website C will have access to all languages, while the Content Editor role for Website B will have access only to the English language @@ -100,15 +100,15 @@ ACL groups, which will be universally reusable for all role groups on any site. :align: center :width: 700 -Groups specific to particular sites (e.g., page group, database mounts) have +Groups specific to particular sites (e.g., page groups, database mounts) have been identified as well as the :samp:`shared groups`, which are universal, -and should be reused across role groups. These shared groups are applicable -for roles dedicated to a single site as well as for cross-site groups. +and reused across role groups. Use shared groups for +for roles for single sites as well as for cross-site groups. -The ACL groups could be further granulated if necessary, by separating permissions +The ACL groups could be further granulated, by separating out permissions for different content elements and dividing records’ related groups into multiple ones — for editing records, managing lists and details through plugins, etc. -It wasn't done here to avoid overly complicating the diagram, which is already +It is not done here to avoid overly complicating the diagram, which is already quite comprehensive. However, in your setup, it might be necessary to create more ACL groups, each responsible for a smaller set of permissions than those shown here. @@ -118,6 +118,6 @@ The desired backend groups structure and aggregation could look like this: :align: center :width: 700 -You should grasp the essence of this concept: numerous smaller backend groups -can be combined to form a Role group. Role groups are the 'top' tier and are -the only ones that can be assigned to users later on. +The key concept that you should grasp here is that small backend groups +are combined to form a Role group. Role groups are the 'top' tier and only they +can be assigned to users later on.