Merge branch 'mjang-doc-private-public-internal' into 'master'

Clarify use of private, public, internal groups

Closes #211811

See merge request gitlab-org/gitlab!35439

doc/development/permissions.md

@@ -13,9 +13,16 @@ Groups and projects can have the following visibility levels:
 - internal (`10`) - an entity is visible to logged in users
 - private (`0`) - an entity is visible only to the approved members of the entity
 
+By default, subgroups can **not** have higher visibility levels.
+For example, if you create a new private group, it can not include a public subgroup.
+
 The visibility level of a group can be changed only if all subgroups and
-sub-projects have the same or lower visibility level. (e.g., a group can be set
-to internal only if all subgroups and projects are internal or private).
+sub-projects have the same or lower visibility level. For example, a group can be set
+to internal only if all subgroups and projects are internal or private.
+
+CAUTION: **Warning:**
+If you migrate an existing group to a lower visibility level, that action does not migrate subgroups
+in the same way. This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/22406).
 
 Visibility levels can be found in the `Gitlab::VisibilityLevel` module.
 

doc/user/group/subgroups/index.md

@@ -19,6 +19,9 @@ By using subgroups you can do the following:
 - **Make it easier to manage people and control visibility.** Give people
   different [permissions](../../permissions.md#group-members-permissions) depending on their group [membership](#membership).
 
+For more information on allowed permissions in groups and projects, see
+[visibility levels](../../../development/permissions.md#general-permissions).
+
 ## Overview
 
 A group can have many subgroups inside it, and at the same time a group can have