Joseph T. Lyons created
Most of the features for collab were previously listed in the section
that was written for private calls. Most of this PR is moving that
content over to the channel documentation and adapting it slightly.
Private calls have similar collaboration, so we can just point back to
the channels doc in that section and keep it pretty thin / DRY.
Release Notes:
- N/Adocs/src/SUMMARY.md | 2
docs/src/collaboration/channels.md | 113 +++++++++++--
docs/src/collaboration/contacts-and-private-calls.md | 18 ++
docs/src/collaboration/overview.md | 12
docs/src/collaboration/private-calls.md | 99 ------------
5 files changed, 120 insertions(+), 124 deletions(-)
@@ -36,7 +36,7 @@
- [Code Completions](./completions.md)
- [Collaboration](./collaboration/overview.md)
- [Channels](./collaboration/channels.md)
- - [Private Calls](./collaboration/private-calls.md)
+ - [Contacts and Private Calls](./collaboration/contacts-and-private-calls.md)
- [Git](./git.md)
- [Debugger](./debugger.md)
- [Diagnostics](./diagnostics.md)
@@ -1,50 +1,123 @@
# Channels
-## Overview
-
Channels provide a way to streamline collaborating for software engineers in many ways, but particularly:
- Pairing – when working on something together, you both have your own screen, mouse, and keyboard.
-- Mentoring – it’s easy to jump in to someone else’s context, and help them get unstuck, without the friction of pushing code up.
+- Mentoring – it's easy to jump in to someone else's context, and help them get unstuck, without the friction of pushing code up.
- Refactoring – you can have multiple people join in on large refactoring without fear of conflict.
- Ambient awareness – you can see what everyone else is working on with no need for status emails or meetings.
-## Channels
-
-To open the collaboration panel hit {#kb collab_panel::ToggleFocus} or `collab panel: toggle focus`.
+Each channel corresponds to an ongoing project or work-stream.
+You can see who's in a channel as their avatars will show up in the sidebar.
+This makes it easy to see what everyone is doing and where to find them if needed.
-Each channel corresponds to an ongoing project or work-stream. You can see who’s in a channel as their avatars will show up in the sidebar. This makes it easy to see what everyone is doing and where to find them if needed.
+Create a channel by clicking the `+` icon next to the `Channels` text in the collab panel.
+Create a subchannel by right clicking an existing channel and selecting `New Subchannel`.
-You can create as many channels as you need. As in the example above, you can mix channels for your day job, as well as side-projects in one instance of Zed.
+You can mix channels for your day job, as well as side-projects in your collab panel.
Joining a channel adds you to a shared room where you can work on projects together.
-## Sharing projects
+_[Join our channel tree to get an idea of how you can organize yours.](https://zed.dev/community-links)_
+
+## Inviting People
+
+By default, channels you create can only be accessed by you.
+You can invite collaborators by right clicking and selecting `Manage members`.
+
+When you have subchannels nested under others, permissions are inherited.
+For instance, adding people to the top-level channel in your channel tree will automatically give them access to its subchannels.
+
+Once you have added someone, they can either join your channel by clicking on it in their Zed sidebar, or you can share the link to the channel so that they can join directly.
+
+## Voice Chat
-After joining a channel, you can `Share` a project with the other people there. This will enable them to edit the code hosted on your machine as though they had it checked out locally.
+You can mute/unmute your microphone via the microphone icon in the upper right-hand side of the window.
-When you are editing someone else’s project, you still have the full power of the editor at your fingertips, you can jump to definitions, use the AI assistant, and see any diagnostic errors. This is extremely powerful for pairing, as one of you can be implementing the current method while the other is reading and researching the correct solution to the next problem. And, because you have your own config running, it feels like you’re using your own machine.
+> Note: When joining a channel, Zed will automatically share your microphone with other users in the call, if your OS allows it.
+> If you'd prefer your microphone to be off when joining a channel, you can do so via the [`mute_on_join`](../configuring-zed.md#calls) setting.
-See [our collaboration documentation](./private-calls.md) for more details about how this works.
+## Sharing Projects
-## Notes
+After joining a channel, you can share a project over the channel via the `Share` button in the upper right-hand side of the window.
+This will allow channel members to edit the code hosted on your machine as though they had it checked out locally.
-Each channel has a notes file associated with it to keep track of current status, new ideas, or to collaborate on building out the design for the feature that you’re working on before diving into code.
+When you are editing someone else's project, you still have the full power of the editor at your fingertips; you can jump to definitions, use the AI assistant, and see any diagnostic errors.
+This is extremely powerful for pairing, as one of you can be implementing the current method while the other is reading and researching the correct solution to the next problem.
+And, because you have your own config running, it feels like you're using your own machine.
+
+We aim to eliminate the distinction between local and remote projects as much as possible.
+Collaborators can open, edit, and save files, perform searches, interact with the language server, etc.
+Guests have a read-only view of the project, including access to language server info.
+
+### Unsharing a Project
+
+You can remove a project from a channel by clicking on the `Unshare` button in the title bar.
+
+Collaborators that are currently in that project will be disconnected from the project and will not be able to rejoin it unless you share it again.
+
+## Channel Notes
+
+Each channel has a Markdown notes file associated with it to keep track of current status, new ideas, or to collaborate on building out the design for the feature that you're working on before diving into code.
This is similar to a Google Doc, except powered by Zed's collaborative software and persisted to our servers.
-## Inviting people
+Open the channel notes by clicking on the document icon to the right of the channel name in the collaboration panel.
-By default, channels you create can only be accessed by you. You can invite collaborators by right clicking and selecting `Manage members`.
+> Note: You can view a channel's notes without joining the channel, if you'd just like to read up on what has been written.
-When you have channels nested under each other, permissions are inherited. For instance, in the example above, we only need to add people to the `#zed` channel, and they will automatically gain access to `#core-editor`, `#new-languages`, and `#stability`.
+## Following Collaborators
-Once you have added someone, they can either join your channel by clicking on it in their Zed sidebar, or you can share the link to the channel so that they can join directly.
+To follow a collaborator, click on their avatar in the top left of the title bar.
+You can also cycle through collaborators using {#kb workspace::FollowNextCollaborator} or `workspace: follow next collaborator` in the command palette.
+
+When you join a project, you'll immediately start following the collaborator that invited you.
+
+When you are in a pane that is following a collaborator, you will:
+
+- follow their cursor and scroll position
+- follow them to other files in the same project
+- instantly swap to viewing their screenshare in that pane, if they are sharing their screen and leave the project
+
+To stop following, simply move your mouse or make an edit via your keyboard.
+
+### How Following Works
+
+Following is confined to a particular pane.
+When a pane is following a collaborator, it is outlined in their cursor color.
+
+Avatars of collaborators in the same project as you are in color, and have a cursor color.
+Collaborators in other projects are shown in gray.
+
+This pane-specific behavior allows you to follow someone in one pane while navigating independently in another and can be an effective layout for some collaboration styles.
+
+### Following a Terminal
+
+You can follow what a collaborator is doing in their terminal by having them share their screen and following it.
+
+In the future, we plan to allow you to collaborate in the terminal directly in a shared project.
+
+## Screen Sharing
+
+Share your screen with collaborators in the current channel by clicking on the `Share screen` (monitor icon) button in the top right of the title bar.
+If you have multiple displays, you can choose which one to share via the chevron to the right of the monitor icon.
+
+After you've shared your screen, others can click on the `Screen` entry under your name in the collaboration panel to open a tab that always keeps it visible.
+If they are following you, Zed will automatically switch between following your cursor in their Zed instance and your screen share, depending on whether you are focused on Zed or another application, like a web browser.
+
+> Note: Collaborators can see your entire screen when you are screen sharing, so be careful not to share anything you don't want to share.
+> Remember to stop screen sharing when you are finished.
## Livestreaming & Guests
-A Channel can also be made Public. This allows anyone to join the channel by clicking on the link.
+A Channel can also be made Public.
+This allows anyone to join the channel by clicking on the link.
Guest users in channels can hear and see everything that is happening, and have read only access to projects and channel notes.
-If you'd like to invite a guest to participate in a channel for the duration of a call you can do so by right clicking on them in the Collaboration Panel. "Allowing Write Access" will allow them to edit any projects shared into the call, and to use their microphone and share their screen if they wish.
+If you'd like to invite a guest to participate in a channel for the duration of a call you can do so by right clicking on them in the Collaboration Panel.
+"Allowing Write Access" will allow them to edit any projects shared into the call, and to use their microphone and share their screen if they wish.
+
+## Leaving a Call
+
+You can leave a channel by clicking on the `Leave call` button in the upper right-hand side of the window.
@@ -0,0 +1,18 @@
+# Contacts and Private Calls
+
+Zed allows you to have private calls / collaboration sessions with those in your contacts.
+These calls can be one-on-ones or contain any number of users from your contacts.
+
+## Adding a Contact
+
+1. In the collaboration panel, click the `+` button next to the `Contacts` section
+1. Search for the contact using their GitHub handle
+ _Note: The contact must be an existing Zed user who has completed the GitHub authentication flow._
+1. Your contact will receive a notification.
+ Once they accept, you'll both appear in each other's contact list.
+
+## Private Calls
+
+Simply click on a contact to start a private call.
+
+_Aside from a few additional features (channel notes, etc.), collaboration in private calls is largely the same as it is in [channels](./channels.md)._
@@ -2,12 +2,16 @@
At Zed, we believe that great things are built by great people working together.
We have designed Zed to help individuals work faster and help teams of people work together more effectively.
-Zed has two mechanisms for collaborating:
-1. [Channels](./channels.md): Ongoing project rooms where team members can share projects, collaborate on code, and maintain ambient awareness of what everyone is working on.
-1. [Private Calls](./private-calls.md): Ad-hoc private collaboration with those in your contacts list.
+In Zed, all collaboration happens in the collaboration panel, which can be opened via {#kb collab_panel::ToggleFocus} or `collab panel: toggle focus` from the command palette.
+You will need to [sign in](../authentication.md#signing-in) in order to access features within the collaboration panel.
+
+## Collaboration panel
-You will need to [sign in](../authentication.md#signing-in) in order to begin using Zed's collaboration features.
+The collaboration panel is broken down into two sections:
+
+1. [Channels](./channels.md): Ongoing project rooms where team members can share projects, collaborate on code, and maintain ambient awareness of what everyone is working on.
+1. [Contacts](./contacts-and-private-calls.md): Ad-hoc private collaboration with those in your contacts list.
---
@@ -1,99 +0,0 @@
-# Private Calls
-
-## Adding a collaborator to a call
-
-Before you can collaborate, you'll need to add a collaborator to your contacts. To do this:
-
-1. Open the contacts menu by clicking on the `Show contacts menu` button in the upper right-hand corner of the window or by running `collab: toggle contacts menu` (`cmd-shift-c`).
-2. Click the add button to the right of the search box.
-3. Search for the contact you want to add using their GitHub handle. Note: the person you are trying to add as a contact must be an existing Zed user.
-
-### Inviting a collaborator
-
-You can add an existing Zed user as a contact from the contacts menu, deployed from the `Show contacts menu` button in the upper right-hand corner of the window or by `collab: toggle contacts menu` (`cmd-shift-c`) and then clicking the `Search for new contact` button to the right of the search box.
-
-
-
-When you invite a collaborator to a project not in a call they will receive a notification to join, and a new call is created.
-
-
-
-### Inviting non-Zed users
-
-If someone you want to collaborate with has not yet signed up for Zed, they will need to [download the app](https://zed.dev/download) and sign in for the first time before you can add them. Identity is tied to GitHub accounts, so new users will need to authenticate with GitHub in order to sign into Zed.
-
-### Voice chat
-
-When joining a call, Zed will automatically share your microphone with other users in the call, if your OS allows it. This isn't tied to your project. You can disable this for your client via the [`mute_on_join`](../configuring-zed.md#calls) setting.
-
-## Collaborating on a project
-
-### Share a project
-
-When you invite a collaborator to join your project, a new call begins. Your Zed windows will show the call participants in the title bar of the window.
-
-
-
-Collaborators in the same project as you are in color, and have a cursor color. Collaborators in other projects are shown in gray. Collaborators that have access to the current project will have their own cursor color under their avatar.
-
-We aim to eliminate the distinction between local and remote projects as much as possible. Collaborators can open, edit, and save files, perform searches, interact with the language server, etc. Guests have a read-only view of the project, including access to language server info.
-
-#### Unshared Projects
-
-If a collaborator is currently in a project that is not shared, you will not be able to jump to their project or follow them until they either share the project or return to a project that is shared.
-
-If you are in a project that isn't shared, others will not be able to join it or see its contents.
-
-### Follow a collaborator
-
-To follow a collaborator, click on their avatar in the top right of the window. You can also cycle through collaborators using `workspace: follow next collaborator` (`ctrl-alt-cmd-f`).
-
-When you join a project, you'll immediately start following the collaborator that invited you.
-
-
-
-When you are in a pane that is following a collaborator, you will:
-
-- follow their cursor and scroll position
-- follow them to other files in the same project
-- instantly swap to viewing their screen in that pane, if they are sharing their screen and leave the project
-
-If you move your cursor or make an edit in that pane, you will stop following.
-
-To start following again, you can click on a collaborator's avatar or cycle through following different participants by pressing `workspace: follow next collaborator` (`ctrl-alt-cmd-f`).
-
-#### How following works
-
-Following is confined to a particular pane. When a pane is following a collaborator, it is outlined in their cursor color.
-
-This pane-specific behavior allows you to follow someone in one pane while navigating independently in another and can be an effective layout for some collaboration styles.
-
-### Sharing your screen
-
-Share your screen with collaborators in the current call by clicking on the `Share screen` button in the top right of the window.
-
-Collaborators will see your screen if they are following you and you start viewing a window outside Zed or a project that is not shared.
-
-Collaborators can see your entire screen when you are screen sharing, so be careful not to share anything you don't want to share. Remember to stop screen sharing when you are finished.
-
-Call participants can open a dedicated tab for your screen share by opening the contacts menu in the top right and clicking on the `Screen` entry if you are sharing your screen.
-
-### Adding a project
-
-You can add a project to a call by clicking on the `Share` button next to the project name in the title bar.
-
-### Removing a project
-
-You can remove a project from a call by clicking on the `Unshare` button next to the project name in the title bar.
-
-Collaborators that are currently in that project will be disconnected from the project and will not be able to rejoin it unless you share it again.
-
-### Following a collaborator's terminal
-
-You can follow what a collaborator is doing in their terminal by having them share their screen and following it.
-
-In the future, we plan to allow you to collaborate in the terminal directly in a shared project.
-
-### Leave call
-
-You can leave a call by opening the contacts menu in the top right and clicking on the `Leave call` button.