help: Update docs to describe group-based permissions.

help/create-user-groups.md

@@ -2,6 +2,13 @@
 
 {!user-groups-intro.md!}
 
+Many organizations find it helpful to create groups for:
+
+- Each team, e.g., “mobile”, “design”, or “IT”.
+- Leadership roles, e.g., “managers”, “engineering-leads”.
+
+{!user-groups-applications.md!}
+
 ## How to create a user group
 
 {!how-to-create-a-user-group.md!}

help/include/review-organization-settings-instructions.md

@@ -1,5 +1,7 @@
-Review the settings for your organization to set everything up how you
-want it to be.
+Review the settings for your organization to set everything up how you want it
+to be.
+
+{!user-groups-intro.md!}
 
 {start_tabs}
 

help/include/sidebar_index.md

@@ -23,11 +23,11 @@
 ## Setting up your organization
 * [Migrating from other chat tools](/help/migrating-from-other-chat-tools)
 * [Create your organization profile](/help/create-your-organization-profile)
+* [Create user groups](/help/create-user-groups)
 * [Customize organization settings](/help/customize-organization-settings)
 * [Create channels](/help/create-channels)
 * [Customize settings for new users](/help/customize-settings-for-new-users)
 * [Invite users to join](/help/invite-users-to-join)
-* [Create user groups](/help/create-user-groups)
 * [Set up integrations](/help/set-up-integrations)
 
 ## Account basics
@@ -168,7 +168,6 @@
 # Zulip administration
 
 ## Organization basics
-* [Review your organization's settings](/help/review-your-organization-settings)
 * [Organization type](/help/organization-type)
 * [Communities directory](/help/communities-directory)
 * [Import from Mattermost](/help/import-from-mattermost)

help/include/user-groups-applications.md

@@ -0,0 +1,9 @@
+Groups provide an easy way to refer to multiple users at once. You can:
+
+- [Mention](/help/mention-a-user-or-group) a group of users,
+  [notifying](/help/dm-mention-alert-notifications) everyone in the group as if
+  they were personally mentioned.
+- Compose a [direct message](/help/direct-messages) to a user group. This
+  automatically puts all the users in the group into the addressee field.
+- Subscribe a user group to a channel. This individually subscribes all the users
+  in the group.

help/include/user-groups-intro.md

@@ -1,14 +1,4 @@
-User groups make it easier to manage any organization with multiple teams or job
-functions. You can:
-
-- Assign permissions to user groups.
-- Add a user group to another user group.
-- Subscribe a user group to a channel. This individually subscribes all the users
-  in the group.
-- [Mention](/help/mention-a-user-or-group) a group of users,
-  [notifying](/help/dm-mention-alert-notifications) everyone in the group as if
-  they were personally mentioned.
-- Compose a [direct message](/help/direct-messages) to a user group. This
-  automatically puts all the users in the group into the addressee field.
-
-You may want to create a user group for each team in your organization.
+User groups offer a flexible way to manage permissions in your organization.
+Most permissions in Zulip can be granted to any combination of
+[roles](/help/roles-and-permissions), [groups](/help/user-groups), and
+individual [users](/help/manage-a-user).

help/manage-user-groups.md

@@ -2,6 +2,8 @@
 
 {!user-groups-intro.md!}
 
+{!user-groups-applications.md!}
+
 ## Create a user group
 
 !!! tip ""
@@ -62,6 +64,10 @@
 
 ## 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.
+
 {start_tabs}
 
 {tab|desktop-web}

help/moving-to-zulip.md

@@ -116,6 +116,9 @@ you will need to upgrade your plan.
 1. [Create your organization profile](/help/create-your-organization-profile),
    which is displayed on your organization's registration and login pages.
 
+1. [Create user groups](/help/create-user-groups), which offer a flexible way to
+   manage permissions.
+
 1. Review [organization permissions](/help/roles-and-permissions), such as who
    can invite users, create channels, etc.
 

help/review-your-organization-settings.md

@@ -1,19 +0,0 @@
-# Review your organization settings
-
-It's good to periodically review your organization's settings. Zulip is in
-active development and is constantly adding new features, and as your
-organization grows, features that may not have been applicable at a small
-scale may be applicable now.
-
-Note that most organization settings are visible to all users, though
-generally only organization administrators can interact with them.
-
-### Review your organization settings
-
-{start_tabs}
-
-{relative|gear|organization-settings}
-
-1. Click on each tab on the left.
-
-{end_tabs}

help/roles-and-permissions.md

@@ -1,12 +1,12 @@
 # Roles and permissions
 
-## User roles
-
 User roles make it convenient to configure different permissions for different
 users in your organization. You can decide what role a user will have when you
 [send them an invitation](/help/invite-new-users), and later [change a user's
 role](/help/roles-and-permissions#change-a-users-role) if needed.
 
+{!user-groups-intro.md!}
+
 !!! tip ""
 
     Learn about [channel permissions](/help/channel-permissions), including
@@ -65,6 +65,7 @@ role](/help/roles-and-permissions#change-a-users-role) if needed.
 ## Related articles
 
 * [Change a user's role](/help/change-a-users-role)
+* [User groups](/help/user-groups)
 * [Channel permissions](/help/channel-permissions)
 * [Inviting new users](/help/invite-new-users)
 * [Zulip Cloud billing](/help/zulip-cloud-billing)

help/user-groups.md

@@ -2,6 +2,8 @@
 
 {!user-groups-intro.md!}
 
+{!user-groups-applications.md!}
+
 ## Browse and join user groups
 
 {start_tabs}