From c40cbd4623e33b94a904eb66e58f92cde5fbba28 Mon Sep 17 00:00:00 2001
From: Alya Abbott <alya@zulip.com>
Date: Mon, 25 Nov 2024 10:22:04 -0800
Subject: [PATCH] help: Improve subgroups documentation.

---
 help/create-user-groups.md           |  4 +++-
 help/include/user-subgroups-intro.md | 13 +++++++++++
 help/manage-user-groups.md           | 34 ++++++++++++++++++++--------
 help/user-groups.md                  |  3 +++
 4 files changed, 44 insertions(+), 10 deletions(-)
 create mode 100644 help/include/user-subgroups-intro.md

diff --git a/help/create-user-groups.md b/help/create-user-groups.md
index ed49a7c6c7..9bc763e4ba 100644
--- a/help/create-user-groups.md
+++ b/help/create-user-groups.md
@@ -7,7 +7,9 @@
 Many organizations find it helpful to create groups for:
 
 - Each team, e.g., “mobile”, “design”, or “IT”.
-- Leadership roles, e.g., “managers”, “engineering-leads”.
+- Leadership roles, e.g., “managers”, “engineering-managers”.
+
+{!user-subgroups-intro.md!}
 
 {!user-groups-applications.md!}
 
diff --git a/help/include/user-subgroups-intro.md b/help/include/user-subgroups-intro.md
new file mode 100644
index 0000000000..dea15b2e77
--- /dev/null
+++ b/help/include/user-subgroups-intro.md
@@ -0,0 +1,13 @@
+You can add a group to another user group, making it easy to express your
+organization's structure in Zulip's permissions system. A user who belongs to a
+subgroup of a group is treated as a member of that group. For example:
+
+- The “engineering” group could be made up of “engineering-managers” and
+  “engineering-staff”.
+- The “managers” group could be made up of “engineering-managers”,
+  “design-managers”, etc.
+
+Updating the members of a group automatically updates the members of all the
+groups that contain it. In the above example, adding a new team member to
+“engineering-managers” automatically adds them to “engineering” and “managers”
+as well. Removing a team member who transferred automatically removes them.
diff --git a/help/manage-user-groups.md b/help/manage-user-groups.md
index 6e1563b938..4109566b5d 100644
--- a/help/manage-user-groups.md
+++ b/help/manage-user-groups.md
@@ -64,11 +64,7 @@
 
 {end_tabs}
 
-## Add groups and users to a group
-
-You can add users to a group, or add a group to any other group. Nesting groups
-makes them easier to maintain. For example, moving a user from one team group to
-another can automatically update what department group they belong to.
+## Add users to a group
 
 {start_tabs}
 
@@ -80,14 +76,16 @@ another can automatically update what department group they belong to.
 
 1. Select the **Members** tab on the right.
 
-1. Under **Add members**, enter groups and users you want to add. You can enter
-   a `#channel` to add all subscribers to the group.
+1. Under **Add members**, enter users you want to add. You can enter a
+   `#channel` to add all subscribers to the group.
 
 1. Click **Add**. Zulip will notify everyone who is added to the group.
 
 {end_tabs}
 
-## Remove users from a user group
+## Add user groups to a group
+
+{!user-subgroups-intro.md!}
 
 {start_tabs}
 
@@ -99,7 +97,25 @@ another can automatically update what department group they belong to.
 
 1. Select the **Members** tab on the right.
 
-1. Under **Members**, find the user you would like to remove.
+1. Under **Add members**, enter groups you want to add.
+
+1. Click **Add**.
+
+{end_tabs}
+
+## Remove user or group from a group
+
+{start_tabs}
+
+{tab|desktop-web}
+
+{relative|group|all}
+
+1. Select a user group.
+
+1. Select the **Members** tab on the right.
+
+1. Under **Members**, find the user or group you would like to remove.
 
 1. Click the **Remove** button in that row. Zulip will notify everyone who is
    removed from the group.
diff --git a/help/user-groups.md b/help/user-groups.md
index d3220ab5ad..daa690e3af 100644
--- a/help/user-groups.md
+++ b/help/user-groups.md
@@ -6,6 +6,9 @@
 
 {!user-groups-applications.md!}
 
+You can add a group to another user group, making it easy to express your
+organization's structure in Zulip's permissions system.
+
 ## Browse and join user groups
 
 {start_tabs}