Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

user docs: Rewrite "Setting up your organization" guide. 

This change depends on #19783, which hasn't been merged yet, to avoid
some broken rendering.
This commit is contained in:
Alya Abbott 2021-09-17 07:50:49 -07:00 committed by Tim Abbott
parent 6a1a665f11
commit 51cecd25c8
26 changed files with 435 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
templates/zerver/help/create-a-stream.md
View File

@ -6,10 +6,10 @@ Organization administrators can
[restrict stream creation](/help/configure-who-can-create-streams) to
admins only, moderators only or to members meeting a minimum account age.
If you are an administrator setting up streams for the first time, we highly
recommend reading our
[guide to streams](/help/getting-your-organization-started-with-zulip#create-streams)
first.
If you are an administrator setting up streams for the first time, check out our
[guide to setting up streams for a new organization][org-guide-new-streams].
[org-guide-new-streams]: /help/getting-your-organization-started-with-zulip#create-streams
## Create a stream

34
templates/zerver/help/create-streams.md Normal file
View File

@ -0,0 +1,34 @@
# Create streams
{!create-streams-intro.md!}
## How to create a stream
{start_tabs}
{relative|stream|all}
1. Click **Create stream** on the right.
1. Fill out the requested info, and click **Create**.
!!! warn ""
**Note**: You will only see the **Create stream** button if you have
permission to create streams.
{end_tabs}
For more details about stream settings, see [Create a stream](/help/create-a-stream#stream-options).
## Tips for creating streams
{!tips-for-creating-streams.md!}
## Related articles
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Create a stream](/help/create-a-stream#stream-options)
* [Stream permissions](/help/stream-permissions)
* [Set default streams for new users](/help/set-default-streams-for-new-users)
* [Getting started with Zulip](/help/getting-started-with-zulip)

39
templates/zerver/help/create-your-organization-profile.md
View File

@ -3,41 +3,22 @@
{!admin-only.md!}
The information in your organization profile is displayed on your
registration and login pages, and in the desktop and mobile apps. As
an example, here is what the registration page for the Zulip community
server looked like at one point:
registration and login pages, and in the Zulip app. Here is an example
registration/login page:
![settings](/static/images/help/organization-profile-example.png)
Note that the Organization description supports full Markdown syntax,
including bold/italic, links, lists, and
[more](/help/format-your-message-using-markdown).
## Edit organization profile
### Create your organization profile
{start_tabs}
{settings_tab|organization-profile}
1. Edit your organization **name**, **description**, and **profile picture**.
1. Click **Save changes**.
{end_tabs}
{!edit-organization-profile.md!}
## Add a wide logo
Zulip also allows you to customize the logo your users see in the upper left
of the main, logged-in view. For best results make sure the logo has a
transparent background, and trim the logo of any bordering whitespace.
{!add-a-wide-logo.md!}
### Add a wide logo
## Related articles
{start_tabs}
{settings_tab|organization-profile}
1. Under **Organization logo**, upload a new logo.
{end_tabs}
Make sure to test the logo in both day mode and [night mode](/help/night-mode).
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Customize organization settings](/help/customize-organization-settings)
* [Create streams](/help/create-streams)
* [Getting started with Zulip](/help/getting-started-with-zulip)

10
templates/zerver/help/customize-organization-settings.md Normal file
View File

@ -0,0 +1,10 @@
# Customize organization settings
{!customize-organization-settings.md!}
## Related articles
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Create your organization profile](/help/create-your-organization-profile)
* [Create streams](/help/create-streams)
* [Getting started with Zulip](/help/getting-started-with-zulip)

10
templates/zerver/help/customize-settings-for-new-users.md Normal file
View File

@ -0,0 +1,10 @@
# Customize settings for new users
{!customize-settings-for-new-users.md!}
## Related articles
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Set default streams for new users](/help/set-default-streams-for-new-users)
* [Invite users to join](/help/invite-users-to-join)
* [Getting started with Zulip](/help/getting-started-with-zulip)

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

@ -1,123 +1,111 @@
# Getting your organization started with Zulip
# Setting up your organization
Use this as a checklist to get your organization off to a great start.
Welcome to Zulip! This page will guide you through trying out Zulip,
migrating your organization from other team chat tools (if needed),
getting everything set up, and inviting others to join.
## Organization settings
If you are joining an existing organization, we recommend checking out
our guide to [Getting started with Zulip][getting-started].
* 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.
[getting-started]: /help/getting-started-with-zulip
* Do a [quick review](/help/review-your-organization-settings)
of all the organization settings available.
If you encounter any problems as you're getting started, please drop
by our [friendly developer community](/developer-community/) and let
us know!
## Trying out Zulip
{!trying-out-zulip.md!}
## Choosing between Zulip Cloud and self-hosting
Whether [signing up for Zulip Cloud](/new/) or [self-hosting
Zulip][install-self-hosted] is the right choice for you depends on the
needs of your organization.
If you aren’t sure what you need, our high quality export and import
tools ([cloud][export-cloud], [self-hosted][export-self-hosted])
ensure you can always move from our hosting to yours (and back).
[install-self-hosted]: https://zulip.readthedocs.io/en/stable/production/install.html
[export-cloud]: /help/export-your-organization
[export-self-hosted]: https://zulip.readthedocs.io/en/latest/production/export-and-import.html
### Advantages of Zulip Cloud
{!advantages-of-zulip-cloud.md!}
### Advantages of self-hosting Zulip
{!advantages-of-self-hosting-zulip.md!}
## Migrating from other chat tools
{!migrating-from-other-chat-tools.md!}
## Create your organization profile
The information in your organization profile is displayed on the
registration and login page for your organization, and in the Zulip app.
### Edit organization profile
{!edit-organization-profile.md!}
### Add a wide logo
{!add-a-wide-logo.md!}
## Customize organization settings
{!customize-organization-settings.md!}
## Create streams
Most messages in Zulip are sent to streams. Streams are similar to chat
rooms, email lists, and IRC/Slack channels, in that they determine who
receives a message. A few suggestions:
{!create-streams-intro.md!}
* It's often better to start with fewer streams, and let the number of
streams grow organically. For small teams, you can start with the default
streams and iterate from there.
### How to create a stream
* For large organizations, we recommend using a consistent naming
scheme, like `#marketing/<name>` or `#mk/<name>` for all streams
pertaining to the marketing team, `#help/<team name>` for
`<team name>`'s internal support stream, etc.
{start_tabs}
* A `#zulip help` stream can be useful for providing internal Zulip support
and answering questions about Zulip.
{relative|stream|all}
* For open source projects or other volunteer organizations, consider
adding default streams like `#announce` for announcements, `#new
members` for new members to introduce themselves and be welcomed,
and `#help` so that there's a clear place users stopping by with
just a single question can post.
1. Click **Create stream** on the right.
* Add clear descriptions to your streams (especially public streams).
1. Fill out the requested info, and click **Create**.
A few relevant help center articles:
{end_tabs}
* [Create a stream](/help/create-a-stream)
For more details about stream settings, see [Create a
stream](/help/create-a-stream#stream-options).
* [Set the default streams](/help/set-default-streams-for-new-users)
for new members.
### Tips for creating streams
* [Rename a stream](/help/rename-a-stream)
{!tips-for-creating-streams.md!}
## Understand topics
## Customize settings for new users
Zulip’s topics are life-changing, but it can take a bit of time for everyone
to learn how to use them effectively. It helps a lot if there are at least a
few people who understand the conversation model at the beginning.
{!customize-settings-for-new-users.md!}
* Read our [guide to streams and topics](/help/streams-and-topics),
and send it out to a few people who you think would be good stewards of
the organization.
## Invite users to join
* If you're unsure at all, create an account on the
[Zulip community server](/developer-community/) and see what topics look
like there.
!!! tip ""
Before inviting users, you may want to [delete any test messages][delete-message]
or [topics](/help/delete-a-topic).
Topics are lightweight and do not need to be managed. Anyone writing to a
stream can and should [start topics](/help/start-a-new-topic) for new
conversations. "Old" topics naturally lose visibility over time, and do not
need to be deleted.
[delete-message]: /help/edit-or-delete-a-message#delete-a-message-completely
### How to invite users to join
{!how-to-invite-users-to-join.md!}
## Set up integrations
Zulip integrates directly with dozens of products, and hundreds more through
[Zapier](/integrations/doc/zapier) and [IFTTT](/integrations/doc/ifttt).
{!set-up-integrations.md!}
The [integrations page](/integrations) has instructions for integrating with
each product.
## Further reading
## Familiarize yourself with Zulip’s feature set
As the administrator of your Zulip organization, you'll be the initial
expert teaching other users how to use Zulip.
* [Review your settings](/help/review-your-settings), and skim the article
names here on the left sidebar.
* Learn the basic [keyboard shortcuts](/help/keyboard-shortcuts) (`n`, `r`, `c`, and `End`).
* Bonus: learn [Markdown message formatting](/help/format-your-message-using-markdown).
* If anything is confusing or feels missing, [contact
us](/help/contact-support)! We love hearing from users.
## Invite users and onboard your community
* [Delete any test messages](/help/edit-or-delete-a-message#delete-a-message-completely)
or [topics](/help/delete-a-topic) you want to delete.
* 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 [everyone is allowed to edit topics](/help/configure-who-can-edit-topics),
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).
- [Automatically linkify](/help/add-a-custom-linkifier)
issue numbers.
- [Write custom integrations](/api/integrations-overview)
for your team’s workflow.
- If your users primarily speak a language other than English,
[set a default language for your organization](/help/change-the-default-language-for-your-organization).
- [Add custom emoji](/help/add-custom-emoji), at the very least for
your organization's logo.
- Link to your Zulip instance with a [nice badge](/help/linking-to-zulip).
- Send feedback to the Zulip development community! We love hearing
about problems (however minor) and feature ideas that could make
Zulip even better.
* [Getting started with Zulip](/help/getting-started-with-zulip)
* [Streams and topics](/help/streams-and-topics)
* [Moderating open organizations](/help/moderating-open-organizations)
* [Using Zulip for a class](/help/using-zulip-for-a-class)

15
templates/zerver/help/include/add-a-wide-logo.md Normal file
View File

@ -0,0 +1,15 @@
{!cloud-standard-only.md!}
You can customize the logo users see in the upper left corner
of the Zulip app. For best results make sure your logo has a
transparent background, and trim any bordering whitespace. To upload a logo:
{start_tabs}
{settings_tab|organization-profile}
1. Under **Organization logo**, upload a new logo.
{end_tabs}
Make sure to test the logo in both light mode and [dark mode](/help/night-mode).

10
templates/zerver/help/include/advantages-of-self-hosting-zulip.md Normal file
View File

@ -0,0 +1,10 @@
* Zulip is [100% open-source software](https://github.com/zulip), with no "open core" catch.
* We work hard to make it easy to [set up][install-zulip],
[backup][backup-zulip], and [maintain][maintain-zulip] a self-hosted
Zulip installation.
* Retain full control over your data.
* Customize Zulip for all your needs.
[install-zulip]: https://zulip.readthedocs.io/en/latest/production/install.html
[backup-zulip]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#backups
[maintain-zulip]: https://zulip.readthedocs.io/en/stable/production/upgrade-or-modify.html

6
templates/zerver/help/include/advantages-of-zulip-cloud.md Normal file
View File

@ -0,0 +1,6 @@
* Simple managed solution, with no setup or maintenance
overhead. [Sign up](/new/) with just a few clicks.
* Always updated to the latest version of Zulip.
* Anyone can [start with Zulip Cloud Free](/new/). [Free or heavily
discounted Zulip Cloud Standard](/plans/) pricing is available for
most non-business uses.

3
templates/zerver/help/include/cloud-standard-only.md Normal file
View File

@ -0,0 +1,3 @@
!!! warn ""
This feature is only available to Zulip Cloud Standard and self-hosted organizations.

13
templates/zerver/help/include/create-streams-intro.md Normal file
View File

@ -0,0 +1,13 @@
In Zulip, streams determine who gets a message. They are similar to
channels in IRC/Slack/Discord, chat rooms, and email lists.
We recommend setting up some streams before inviting other users to
join Zulip, so that you can [automatically subscribe
everyone](/help/set-default-streams-for-new-users) to the right set of
streams.
If you later create additional streams, no worries! You can always add
a group of users or all the members of another stream to a new stream.
!!! tip ""
Add clear descriptions to your streams, especially public streams.

40
templates/zerver/help/include/customize-organization-settings.md Normal file
View File

@ -0,0 +1,40 @@
Review the settings for your organization to set everything up how you
want it to be.
{start_tabs}
{relative|gear|manage-organization}
1. Click on "Organization settings" and "Organization permissions"
tabs, and any others that are of interest.
{end_tabs}
A few settings to highlight:
* Decide [who can invite new users][who-can-invite], or whether
[anyone can join][who-can-join].
* [Set visibility for users' email addresses][email-address-visibility].
* If your organization uses a programming language, set the [default
language for code blocks][default-code-block-language]. Also
consider setting up [code playgrounds][code-playgrounds].
* If your organization uses code repositories, [set up
linkifiers](/help/add-a-custom-linkifier) to make it easy to link to
issues (e.g. just by typing #1234 for issue 1234).
* [Add custom emoji](/help/add-custom-emoji), including your organization's logo.
For many other settings, e.g. [message and topic editing
permissions][topic-editing-permissions], you can experience how Zulip
works for your organization before deciding what settings are best for
you.
[topic-editing-permissions]: /help/configure-message-editing-and-deletion
[default-code-block-language]: /help/code-blocks#default-code-block-language
[code-playgrounds]: /help/code-blocks#code-playgrounds
[email-address-visibility]: /help/restrict-visibility-of-email-addresses
[who-can-invite]: /help/invite-new-users#change-who-can-send-invitations
[who-can-join]: /help/allow-anyone-to-join-without-an-invitation

8
templates/zerver/help/include/customize-settings-for-new-users.md Normal file
View File

@ -0,0 +1,8 @@
Customize settings for new users to get them off to a great start.
* [Add custom profile fields](/help/add-custom-profile-fields).
* [Set default streams for new users](/help/set-default-streams-for-new-users).
* [Set the default language for new users][change-default-language],
if it should be something other than US English.
[change-default-language]: /help/change-the-default-language-for-your-organization

15
templates/zerver/help/include/edit-organization-profile.md Normal file
View File

@ -0,0 +1,15 @@
!!! tip ""
The organization description supports [full Markdown syntax][markdown-syntax],
including **bold**/*italic*, links, lists, and more.
{start_tabs}
{settings_tab|organization-profile}
1. Edit your organization **name**, **description**, and **profile picture**.
1. Click **Save changes**.
{end_tabs}
[markdown-syntax]: /help/format-your-message-using-markdown

27
templates/zerver/help/include/how-to-invite-users-to-join.md Normal file
View File

@ -0,0 +1,27 @@
{start_tabs}
{tab|require-invitations}
1. Configure [allowed authentication
methods](/help/configure-authentication-methods). By default, Zulip
allows logging in via email/password as well as various social
authentication providers like Google, GitHub, GitLab, and Apple.
2. [Invite users](/help/invite-new-users) by [sending out an email or
sharing a reusable invite
link](/help/invite-new-users#send-invitations). Note that on most
Zulip servers (including Zulip Cloud), email invitations and
reusable invitation links expire 10 days after they are sent.
{tab|allow-anyone-to-join}
1. [Allow anyone to join][allow-anyone-to-join] without an invitation.
2. Share a link to your registration page, which is
https://your-domain.zulipchat.com for Zulip Cloud organizations.
{end_tabs}
!!! tip ""
You can link to your Zulip organization with a [nice badge](/help/linking-to-zulip).
[allow-anyone-to-join]: /help/allow-anyone-to-join-without-an-invitation

10
templates/zerver/help/include/migrating-from-other-chat-tools.md Normal file
View File

@ -0,0 +1,10 @@
We have tools for importing your data from other chat tools, including
users, channels, messages, and more.
Note that importing data from another chat app creates a new
Zulip organization containing only imported data.
* [Import from Slack](/help/import-from-slack)
* [Import from Mattermost](/help/import-from-mattermost)
* [Import from Gitter](/help/import-from-gitter)
* [Import from Rocket.Chat](/help/import-from-rocketchat)

13
templates/zerver/help/include/set-up-integrations.md Normal file
View File

@ -0,0 +1,13 @@
Zulip integrates directly with dozens of products, and with hundreds
more through [Zapier](/integrations/doc/zapier) and
[IFTTT](/integrations/doc/ifttt). Popular Zulip integrations include
[GitHub](/integrations/doc/github), [Jira](/integrations/doc/jira),
[PagerDuty](/integrations/doc/pagerduty),
[Sentry](/integrations/doc/sentry) and
[Twitter](/integrations/doc/twitter).
* The [integrations page](/integrations) has instructions for
integrating with each product.
* If you don't see an integration you need, you can [request it](/help/request-an-integration).
* You can also [create custom integrations](/api/integrations-overview) using our API.
* Want to learn more? Read about [Zulip bots and integrations](/help/bots-and-integrations).

12
templates/zerver/help/include/sidebar_index.md
View File

@ -18,6 +18,17 @@
* [Replying to messages](/help/replying-to-messages)
* [Messaging tips & tricks](/help/messaging-tips)
## Setting up your organization
* [Trying out Zulip](/help/trying-out-zulip)
* [Zulip Cloud or self-hosting?](/help/zulip-cloud-or-self-hosting)
* [Migrating from other chat tools](/help/migrating-from-other-chat-tools)
* [Create your organization profile](/help/create-your-organization-profile)
* [Customize organization settings](/help/customize-organization-settings)
* [Create streams](/help/create-streams)
* [Customize settings for new users](/help/customize-settings-for-new-users)
* [Invite users to join](/help/invite-users-to-join)
* [Set up integrations](/help/set-up-integrations)
## Account basics
* [Change your name](/help/change-your-name)
* [Change your email address](/help/change-your-email-address)
@ -124,7 +135,6 @@
## Organization basics
* [Review your organization's settings](/help/review-your-organization-settings)
* [Create your organization profile](/help/create-your-organization-profile)
* [Import from Mattermost](/help/import-from-mattermost)
* [Import from Slack](/help/import-from-slack)
* [Import from Gitter](/help/import-from-gitter)

17
templates/zerver/help/include/tips-for-creating-streams.md Normal file
View File

@ -0,0 +1,17 @@
* It's often best to start with just a few streams, and add more as
needed. For small teams, you can start with the default streams and
go from there.
* For large organizations, we recommend using a consistent naming
scheme, like `#marketing/<name>` or `#mk/<name>` for all streams
pertaining to the marketing team, `#help/<team name>` for
`<team name>`'s internal support stream, etc.
* A `#zulip help` stream can be useful for providing internal Zulip
support and answering questions about Zulip.
* For open source projects or other volunteer organizations, consider
adding default streams like `#announce` for announcements, `#new
members` for new members to introduce themselves and be welcomed,
and `#help` so that there's a clear place users stopping by with
just a single question can post.

11
templates/zerver/help/include/trying-out-zulip.md Normal file
View File

@ -0,0 +1,11 @@
You can start by reading about how [Zulip’s](/hello/) unique
topic-based threading [combines the best of email and
chat](/why-zulip/) to make [remote work](/for/companies/) productive
and delightful.
We also highly recommend trying Zulip for yourself! You can:
* [Create a Zulip Cloud organization](/new/) for free with just a few
clicks.
* [Join the Zulip developer community](/developer-community/) to see
Zulip in action. Feel free to introduce yourself and ask questions!

2
templates/zerver/help/include/when-to-start-a-new-topic.md
View File

@ -1,4 +1,4 @@
To get the full benefits of Zulip's topic model, When starting a new
To get the full benefits of Zulip's topic model, when starting a new
conversation, you should start a new topic!
Starting a topic is like a lighter weight version of giving your email a subject.

20
templates/zerver/help/invite-users-to-join.md Normal file
View File

@ -0,0 +1,20 @@
# Invite users to join
!!! tip ""
Before inviting users, you may want to [delete any test messages][delete-message]
or [topics](/help/delete-a-topic).
[delete-message]: /help/edit-or-delete-a-message#delete-a-message-completely
## How to invite users to join
{!how-to-invite-users-to-join.md!}
## Related articles
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Invite new users](/help/invite-new-users)
* [Allow anyone to join](/help/allow-anyone-to-join-without-an-invitation)
* [Set default streams for new users](/help/set-default-streams-for-new-users)
* [Customize settings for new users](/help/customize-settings-for-new-users)
* [Getting started with Zulip](/help/getting-started-with-zulip)

11
templates/zerver/help/migrating-from-other-chat-tools.md Normal file
View File

@ -0,0 +1,11 @@
# Migrating from other chat tools
{!migrating-from-other-chat-tools.md!}
## Related articles
* [Zulip Cloud or self-hosting?](/help/zulip-cloud-or-self-hosting)
* [Trying out Zulip](/help/trying-out-zulip)
* [Installing a Zulip server](https://zulip.readthedocs.io/en/stable/production/install.html)
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Getting started with Zulip](/help/getting-started-with-zulip)

10
templates/zerver/help/set-up-integrations.md Normal file
View File

@ -0,0 +1,10 @@
# Set up integrations
{!set-up-integrations.md!}
## Related articles
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Bots and integrations](/help/bots-and-integrations)
* [Add a bot or integration](/help/add-a-bot-or-integration)
* [Add a custom linkifier](/help/add-a-custom-linkifier)

11
templates/zerver/help/trying-out-zulip.md Normal file
View File

@ -0,0 +1,11 @@
# Trying out Zulip
{!trying-out-zulip.md!}
## Related articles
* [Getting started with Zulip](/help/getting-started-with-zulip)
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Zulip Cloud or self-hosting?](/help/zulip-cloud-or-self-hosting)
* [Migrating from other chat tools](/help/migrating-from-other-chat-tools)
* [Streams and topics](/help/streams-and-topics)

30
templates/zerver/help/zulip-cloud-or-self-hosting.md Normal file
View File

@ -0,0 +1,30 @@
# Choosing between Zulip Cloud and self-hosting
Whether [signing up for Zulip Cloud](/new/) or [self-hosting
Zulip][install-self-hosted] is the right choice for you depends on the
needs of your organization.
If you aren’t sure what you need, our high quality export and import
tools ([cloud][export-cloud], [self-hosted][export-self-hosted])
ensure you can always move from our hosting to yours (and back).
## Advantages of Zulip Cloud
{!advantages-of-zulip-cloud.md!}
## Advantages of self-hosting Zulip
{!advantages-of-self-hosting-zulip.md!}
## Related resources
* [Sign up for Zulip Cloud](/new/)
* [Installing a Zulip server](https://zulip.readthedocs.io/en/stable/production/install.html)
* [Trying out Zulip](/help/trying-out-zulip)
* [Setting up your organization](/help/getting-your-organization-started-with-zulip)
* [Migrating from other chat tools](/help/migrating-from-other-chat-tools)
* [Getting started with Zulip](/help/getting-started-with-zulip)
[install-self-hosted]: https://zulip.readthedocs.io/en/stable/production/install.html
[export-cloud]: /help/export-your-organization
[export-self-hosted]: https://zulip.readthedocs.io/en/latest/production/export-and-import.html