help: Rework docs for joining and inviting.

docs/tutorials/new-feature-tutorial.md

@@ -668,12 +668,3 @@ documenting the feature to `templates/zerver/help/` in the main Zulip
 server repository, where the source for Zulip's user documentation is
 stored. For information on writing user documentation, see
 [Zulip's general user guide documentation](../subsystems/user-docs.html).
-
-For a more concrete example of writing documentation for a new
-feature, see [an example commit in the Zulip repo][example-commit]
-that documented a realm feature, [the current source][example-current-source],
-and [the final rendered documentation][example-docs].
-
-[example-commit]: https://github.com/zulip/zulip/commit/ce1875533e27a6ec5aab02260dde5f76976ff326
-[example-current-source]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/manage-who-can-join-and-invite.md
-[example-docs]: https://chat.zulip.org/help/manage-who-can-join-and-invite

templates/zerver/for/open-source.md

@@ -21,7 +21,7 @@ support@zulipchat.com.
 ### Join without an invitation
 
 Allow anyone to
-[join without an invitation](/help/manage-who-can-join-and-invite).
+[join without an invitation](/help/allow-anyone-to-join-without-an-invitation).
 You can also link to your Zulip with a [badge](/help/join-zulip-chat-badge)
 in your readme document.
 

templates/zerver/help/allow-anyone-to-join-without-an-invitation.md

@@ -0,0 +1,23 @@
+# Allow anyone to join without an invitation
+
+{!admin-only.md!}
+
+By default, users need an invitation to join. You can open your Zulip
+up so that anyone can join without an invitation.
+
+{start_tabs}
+
+1. Set [default streams](/help/set-default-streams-for-new-users) for new users.
+
+{settings_tab|organization-permissions}
+
+1. Find the section **Joining the organization**.
+
+1. Set **Are invitations required for joining the organization** to **No**.
+
+1. Set **Restrict email domains of new users?** to either
+   **Don't allow disposable email addresses** (recommended) or **No**.
+
+1. Click **Save changes**.
+
+{end_tabs}

templates/zerver/help/getting-your-organization-started-with-zulip.md

@@ -4,10 +4,6 @@ Use this as a checklist to get your organization off to a great start.
 
 ## Organization settings
 
-* Set a policy for [who can join the organization](/help/manage-who-can-join-and-invite).
-
-* Configure [allowed authentication methods](/help/configure-authentication-methods).
-
 * Add an organization [icon and description](/help/create-your-organization-profile) to
   customize your login/registration pages as well as how your
   organization appears in the desktop and mobile apps.
@@ -84,19 +80,23 @@ expert teaching other users how to use Zulip.
 
 * [Delete any test messages](/help/edit-or-delete-a-message#delete-a-message-completely)
   or [topics](/help/delete-a-topic) you want to delete.
-* Use the `#zulip` stream to answer questions and share tips on how to use
-  Zulip effectively.
+
+* Configure
+  [allowed authentication methods](/help/configure-authentication-methods),
+  and [invite users](/help/invite-new-users).
+
 * If you have an existing chat tool, make sure everyone knows that the
   team is switching, and why. The team should commit to use Zulip
   exclusively **for at least a week** to make an effective trial;
   stragglers will result in everyone having a bad experience.
+
 * If [community topic edits](/help/community-topic-edits) are enabled,
   encourage a few people to help rename topics for the first few days, while
   everyone is still getting used to the new conversation model.
 
 ## Bonus things to set up
 
-* [Add custom profile fields](/help/add-custom-profile-fields)
+* [Add custom profile fields](/help/add-custom-profile-fields).
 - [Automatically linkify](/help/add-a-custom-linkification-filter)
   issue numbers.
 - [Write custom integrations](/api/integrations-overview)

templates/zerver/help/include/sidebar_index.md

@@ -52,7 +52,6 @@
 * [View a message's edit history](/help/view-a-messages-edit-history)
 
 ## People
-* [Invite users](/help/invite-users)
 * [Check whether someone is on-line](/help/check-whether-someone-is-here-or-away)
 * [View someone's profile](/help/view-someones-profile)
 
@@ -109,7 +108,6 @@
 * [Import from HipChat/Stride](/help/import-from-hipchat)
 * [Import from Slack](/help/import-from-slack)
 * [Import from Gitter](/help/import-from-gitter)
-* [Manage who can join](/help/manage-who-can-join-and-invite)
 * [Roles and permissions](/help/roles-and-permissions)
 * [Set the default language for new users](/help/change-the-default-language-for-your-organization)
 * [Export your organization](/help/export-your-organization)
@@ -132,6 +130,8 @@
 * [Add a custom linkification filter](/help/add-a-custom-linkification-filter)
 
 ## Users & bots
+* [Invite new users](/help/invite-new-users)
+* [Allow anyone to join](/help/allow-anyone-to-join-without-an-invitation)
 * [Deactivate or reactivate a user](/help/deactivate-or-reactivate-a-user)
 * [Deactivate or reactivate a bot](/help/deactivate-or-reactivate-a-bot)
 * [Restrict bot creation](/help/restrict-bot-creation)

templates/zerver/help/invite-new-users.md

@@ -0,0 +1,142 @@
+# Invite new users
+
+There are a number of ways to grant access to your Zulip organization.
+
+* Allow **anyone to join** without an invitation.
+
+* Allow people to join based on the **domain** of their email address.
+
+* Send **email invitations** to up to 100 addresses at a time.
+
+* Share a **reusable invitation link**.
+
+This article will cover these methods in detail.
+
+You can also manage access by
+[controlling how users authenticate](/help/configure-authentication-methods)
+to Zulip.  For example, you could allow anyone to join without an
+invitation, but require them to authenticate via LDAP.
+
+## Enable email signup
+
+{start_tabs}
+
+{tab|restrict-by-email-domain}
+
+1. Set [default streams](/help/set-default-streams-for-new-users) for new users.
+
+{settings_tab|organization-permissions}
+
+1. Find the section **Joining the organization**.
+
+1. Set **Are invitations required for joining the organization** to **No**.
+
+1. Set **Restrict email domains of new users?** to
+   **Restrict to a list of domains**.
+
+1. Enter any number of domains. For each domain, check or uncheck
+   **Allow subdomains**.
+
+1. Click **Save changes**.
+
+{tab|allow-anyone-to-join}
+
+1. Set [default streams](/help/set-default-streams-for-new-users) for new users.
+
+{settings_tab|organization-permissions}
+
+1. Find the section **Joining the organization**.
+
+1. Set **Are invitations required for joining the organization** to **No**.
+
+1. Set **Restrict email domains of new users?** to either
+   **Don't allow disposable email addresses** (recommended) or **No**.
+
+1. Click **Save changes**.
+
+{end_tabs}
+
+Before anyone joins your organization this way, we'll send a validation link
+to verify their email address.
+
+## Send invitations
+
+By default, organization admins and members can send
+invitations. Organization admins can also change who can send invitations.
+
+Note that on most Zulip servers (including Zulip Cloud), email invitations
+and reusable invitation links expire 10 days after they are sent.
+
+{start_tabs}
+
+{tab|send-email-invitations}
+
+{relative|gear|invite}
+
+1. Enter a list of email addresses.
+
+1. Decide whether the users should join as admins, members, or guests.
+
+1. Select which streams they should join. If you send invitations often, you
+   may want to configure a set of
+   [default streams](/help/set-default-streams-for-new-users).
+
+1. Click **Invite**.
+
+!!! warn ""
+    You will only see **Invite users** in the gear menu if you have
+    permission to invite users.
+
+{tab|share-an-invite-link}
+
+{relative|gear|invite}
+
+1. Click **Generate invite link**.
+
+1. Decide whether users using the link should join as admins, members, or
+   guests.
+
+1. Select which streams they should join. If you send invitations often, you
+   may want to configure a set of
+   [default streams](/help/set-default-streams-for-new-users).
+
+1. Click **Generate invite link**.
+
+1. Copy the link, and send it to anyone you'd like to invite.
+
+!!! warn ""
+    You will only see **Invite users** in the gear menu if you have
+    permission to invite users.
+
+{end_tabs}
+
+## Change who can send invitations
+
+By default, organization admins and members can send invitations. You can
+restrict invites to admins only.
+
+{start_tabs}
+
+{settings_tab|organization-permissions}
+
+1. Under Joining the organization, set
+   **Are invitations required for joining the organization?** to
+   **Yes. Only admins can send invitations**.
+
+1. Click **Save changes**.
+
+{end_tabs}
+
+## Manage pending invitations
+
+Organization administrators can revoke or resend any invitation or reusable
+invitation link.
+
+{start_tabs}
+
+{settings_tab|invites-list-admin}
+
+1. From here, you can view pending invitations, **Revoke** email invitations
+   and invitation links, or **Resend** email invitations.
+
+{end_tabs}

templates/zerver/help/invite-users.md

@@ -1,24 +0,0 @@
-# Invite users
-
-By default, users need an invitation to join your Zulip organization, and
-all members other than guests can invite others.
-
-Organization administrators can also
-[modify who can join and invite](/help/manage-who-can-join-and-invite) in a
-variety of ways.
-
-{relative|gear|invite}
-
-1. Enter a list of **email addresses**, decide whether the new users should
-   **join as admins, members, or guests**, and select the **streams they should join**.
-
-1. Click **Invite**.
-
-!!! warn ""
-    You will only see **Invite users** in the gear menu if you have
-    permission to invite users.
-
-## Default streams
-
-If you're frequently adding users to your organization, you may want to
-[set default streams for new users](/help/set-default-streams-for-new-users).

templates/zerver/help/join-a-zulip-organization.md

@@ -4,7 +4,7 @@ By default, Zulip organizations require an invitation to join.
 
 Organization administrators can also allow anyone to join without an
 invitation, and/or restrict user email addresses to a company domain. See
-[manage who can join and invite](/help/manage-who-can-join-and-invite).
+[inviting new users](/help/invite-new-users).
 
 ## Check if you need an invitation to join
 
@@ -36,10 +36,13 @@ invitation, and/or restrict user email addresses to a company domain. See
 
 ## Accept an invitation
 
-Invitations to Zulip organizations come by email. Look for an email from
-Zulip. It may take a few minutes for the invitation email to reach your
+Invitations to Zulip organizations often come by email. Look for an email
+from Zulip. It may take a few minutes for the invitation email to reach your
 inbox.
 
+Alternatively, an organization administrator may have sent you an invitation
+link via another method.
+
 ## Tips
 
 * If you are joining multiple Zulip organizations, we recommend

templates/zerver/help/manage-who-can-join-and-invite.md

@@ -1,18 +0,0 @@
-# Manage who can join and invite
-
-{!admin-only.md!}
-
-By default, users need an invitation to join. You can additionally
-**allow only administrators to send invitations**.
-
-Alternatively, you can **allow anyone to join without an invitation**. In
-this case, you can also **disallow disposable email addresses**, or
-**restrict new users to a list of email domains** (e.g. `corp.example.com`, or `*.example.com`).
-
-{settings_tab|organization-permissions}
-
-1. Under **Joining the organization**, configure **Are invitations required for joining the organization**.
-
-1. Under **Joining the organization**, configure **Restrict email domains of new users**.
-
-{!save-changes.md!}

templates/zerver/help/moderating-open-organizations.md

@@ -1,12 +1,12 @@
 # Moderating open organizations
 
 An **open organization** is one where
-[anyone can join without an invitation](/help/manage-who-can-join-and-invite).
+[anyone can join without an invitation](/help/allow-anyone-to-join-without-an-invitation).
 Moderation is a big part of making an open community work.
 
 ## Prevention
 
-* [Disallow disposable email addresses](/help/manage-who-can-join-and-invite),
+* [Disallow disposable email addresses](/help/allow-anyone-to-join-without-an-invitation)
   or [require users to log in via GitHub](/help/configure-authentication-methods).
 * Restrict who can [create streams](/help/configure-who-can-create-streams),
   [create bots](/help/restrict-bot-creation) or

templates/zerver/security.md

@@ -43,7 +43,7 @@ priority.
   synchronizing these data from another database (such as
   [LDAP/Active Directory][ldap-name]).
 - Zulip provides many options for
-  [managing who can join the organization](/help/manage-who-can-join-and-invite),
+  [managing who can join the organization](/help/invite-new-users),
   supporting everything from open to the public (e.g. for open source
   projects), to requiring an invitation to join, to having an email from a
   list of domains, to being a member of a specific organization in

zerver/lib/bugdown/tabbed_sections.py

@@ -51,6 +51,11 @@ TAB_DISPLAY_NAMES = {
     'cloud': 'HipChat Cloud',
     'server': 'HipChat Server or Data Center',
     'stride': 'Stride',
+
+    'send-email-invitations': 'Send email invitations',
+    'share-an-invite-link': 'Share an invite link',
+    'allow-anyone-to-join': 'Allow anyone to join',
+    'restrict-by-email-domain': 'Restrict by email domain',
 }
 
 class TabbedSectionsGenerator(Extension):