diff --git a/docs/main/administration-guide/administration-guide-index.mdx b/docs/main/administration-guide/administration-guide-index.mdx index 0f5210b09e9..be739a010f2 100644 --- a/docs/main/administration-guide/administration-guide-index.mdx +++ b/docs/main/administration-guide/administration-guide-index.mdx @@ -5,7 +5,7 @@ Welcome to the Mattermost Administration Guide. This guide is organized around w - [Configure](/administration-guide/configure/configure-index) - System Console settings, search, email, file storage, branding, agents, and plugins. - [Onboard users](/administration-guide/onboard/onboard-index) - Single sign-on, AD/LDAP, provisioning, and guest accounts. -- [Manage](/administration-guide/manage/admin/server-maintenance) - Access control, server operations, licensing, Cloud workspaces, and notices. +- [Manage](/administration-guide/manage/admin/server-maintenance) - Workspace organization, access control, server operations, licensing, Cloud workspaces, and notices. - [Monitor and troubleshoot](/administration-guide/manage/admin/monitoring-and-performance) - Metrics and dashboards, logging, health checks, support packets, and error codes. - [Comply](/administration-guide/comply/comply-index) - Compliance export and monitoring, eDiscovery, data retention, legal hold, and audit logs. - [Upgrade](/administration-guide/upgrade/upgrade-index) - Upgrade notes, upgrade and downgrade procedures, and post-upgrade rollout tasks. diff --git a/docs/main/administration-guide/manage/admin/user-management.mdx b/docs/main/administration-guide/manage/admin/user-management.mdx index 0ed472ce51f..f3f5de9cddc 100644 --- a/docs/main/administration-guide/manage/admin/user-management.mdx +++ b/docs/main/administration-guide/manage/admin/user-management.mdx @@ -14,4 +14,4 @@ Who can do what in a workspace that's already running: the roles and permissions - [Team channel policies](/administration-guide/manage/admin/abac-team-channel-policies) - Channel membership policies Team Admins manage from Team Settings. - [Channel-specific access rules](/administration-guide/manage/admin/abac-channel-access-rules) - Access rules Channel Admins manage from Channel Settings. -Setting up authentication and creating accounts in the first place is covered in [onboard users](/administration-guide/onboard/onboard-index), including [guest accounts](/administration-guide/onboard/guest-accounts). +Setting up authentication and creating accounts in the first place is covered in [onboard users](/administration-guide/onboard/onboard-index), including [guest accounts](/administration-guide/onboard/guest-accounts). For guidance on how to structure teams and channels before you decide who can create them, see [workspace organization](/administration-guide/manage/admin/workspace-organization). diff --git a/docs/main/administration-guide/manage/admin/workspace-organization.mdx b/docs/main/administration-guide/manage/admin/workspace-organization.mdx new file mode 100644 index 00000000000..9cf15a212b5 --- /dev/null +++ b/docs/main/administration-guide/manage/admin/workspace-organization.mdx @@ -0,0 +1,252 @@ +--- +title: "Workspace organization" +--- + + +There's no single correct way to organize a Mattermost workspace. The right structure depends on the size of your organization, your security requirements, and how your people work together. This guide offers recommended starting points and the trade-offs behind them. + +Workspace organization comes down to 3 decisions: + +1. How many teams you create, and what each team represents. +2. How channels are named and grouped within those teams. +3. Who is allowed to create and manage teams and channels. + +These decisions depend on each other. A team structure that matches how people actually work makes channel organization easier, and your permission model is what enforces the security boundaries that structure is meant to create. + +## Choose a team structure + +Teams form the top level of organization in Mattermost. They define who collaborates together and what information they can access, which is how you maintain data sovereignty, compliance, and operational clarity across the deployment. + +Each team is an independent workspace with its own members, channels, permissions, and integrations. That separation creates clear boundaries between groups that rarely collaborate, or that operate under different levels of data sensitivity or access control. Think of a team as a secure collaboration enclave: a contained environment where people can freely share information relevant to their work. + +The most useful question isn't how to organize your teams, it's how many you actually need. The answer is usually fewer than expected. Use teams to separate populations that shouldn't share data or that don't work together often. + +| Operational boundary | Recommended structure | Example teams | +|---|---|---| +| **None** | A single team. [Channel types](/end-user-guide/collaborate/channel-types) and [access controls](/administration-guide/manage/admin/user-management) manage access to information within it, so one team doesn't mean everyone sees everything. | `Acme Company` | +| **Security boundaries** | One team per boundary. Separation covers more than channels: it also limits which people and integrations each group can see, and lets you give each population the permission set your compliance policies require. | `Field Ops`, `R&D`, `Regulatory Compliance` | +| **Business unit segmentation** | One team per business unit, subsidiary, or region, with an optional organization-wide team for announcements. Gives each unit autonomy and its own compliance posture within one deployment. | `Americas`, `EMEA`, `APAC` | +| **External access control** | A separate team for external collaboration, isolating partners and contractors from internal systems. Use [connected workspaces](/administration-guide/onboard/connected-workspaces) instead when your partners also run Mattermost. | `Core Platform`, `Integration Partners`, `Customer Deployments` | + + + +**Watch for team sprawl.** Teams created without a clear policy accumulate into a list nobody can navigate. Warning signs include people who belong to many teams but use only a few, notification overload, and new users who can't tell which teams matter. + +If your deployment shows these signs, restrict who can create teams in **System Console \> User Management \> Permissions**, [archive inactive teams](/end-user-guide/collaborate/organize-using-teams#archive-a-team) in **System Console \> Teams**, and move structure into channels and [categories](#organize-the-sidebar). + + + +### Single team + +Best for organizations with fewer than about 2,000 users under a single security boundary, with no need to isolate groups from one another. Everyone shares one workspace. Channels, [categories](/end-user-guide/preferences/customize-your-channel-sidebar), and naming conventions carry all the structure. This model is the easiest to administer and gives people the broadest visibility across the organization. + +A single team still gives you control over who sees what. Private channels limit membership, and [access control policies](/administration-guide/manage/admin/attribute-based-access-control) can gate channels on user attributes without splitting the workspace into separate teams. + +**Use a single team when:** + +- Your organization has a unified directory (one IdP, one LDAP/SAML source). +- All users operate at the same classification level or sensitivity tier. +- You want maximum visibility and searchability across the organization. +- Your user count stays manageable within one channel list. + +**Avoid a single team when:** + +- You need to prevent certain groups from even seeing that other channels or users exist. +- You have subsidiaries, partner organizations, or external users who shouldn't mix with your internal workspace. +- Notification volume from the full organization would overwhelm individual users. + +### Multiple teams by security boundary + +Best for organizations where different populations must be separated by classification level, role, or data sensitivity — not just for organizational clarity, but as a security control. Populations in separate teams have no visibility into each other's channels, including public ones. A red team and a blue team, for example, stay fully hidden from each other: planned attack methods on one side, detection rules and alert thresholds on the other. + +![A multi-team workspace with a classification banner and isolated teams for different security boundaries.](/images/workspace-org-security-boundary-teams.png) + +The boundary covers more than channels. Integrations such as webhooks and slash commands are created within a team and stay scoped to it, and a [team override scheme](/administration-guide/onboard/advanced-permissions#team-override-scheme) lets each population run under the permission set its compliance obligations call for. + +To keep people from discovering users outside their own team, do both of the following: + +1. In **System Console \> Site Configuration \> Users and Teams**, set [Enable users to open direct message channels with](/administration-guide/configure/site-configuration-settings#enable-users-to-open-direct-message-channels-with) to **Any member of the team**. That restricts the Direct Messages menu and Find channel to people on the team currently being viewed. +2. Set each security-boundary team to [Private Team](/end-user-guide/collaborate/team-settings#discoverability), so users who aren't already members can't find or join it. + +**Use multiple teams by security boundary when:** + +- Your organization operates at multiple classification levels (for example, FOUO, CUI, or classified). +- Two populations must stay mutually invisible, such as separately compartmented program offices. +- A small group must stay sealed off from the rest of the organization for regulatory reasons, such as a deal team running acquisition due diligence before an announcement. +- Your compliance posture requires demonstrable access separation at the collaboration layer. + +Pair this pattern with [attribute-based access control](/administration-guide/manage/admin/attribute-based-access-control) to automate team and channel membership from identity-provider attributes. + +### Multiple teams by business unit + +Best for large organizations with distinct business units, group companies, or subsidiaries that operate independently but share a single Mattermost server. Each major unit gets its own team. An organization-wide team with announcement channels is optional. Within each team, people organize by project and function using channels and categories. Common examples include a financial services firm with a team per subsidiary, or a conglomerate whose group companies share infrastructure but operate independently. + +**Use multiple teams by business unit when:** + +- Different parts of your organization need meaningfully different channel structures and policies. +- You want to limit sidebar noise for people who only need visibility into their own unit. +- Performance is a concern — multiple teams distribute database query load. + +**Watch out for:** + +- **Team sprawl.** Creating a team for every project or sub-group, rather than using channels, recreates the sprawl problem at the team level. Set a policy for what warrants a new team versus a new channel. +- **Cross-team collaboration gaps.** Users in separate teams can't share a channel. For cross-unit projects, use a shared team that both populations can join. + +### Multiple teams for external access + +Best for organizations that regularly collaborate with contractors, partners, customers, or coalition partners who shouldn't have full access to the internal workspace. One approach is a dedicated team (or set of teams) for external collaboration. Internal users can belong to both internal and external-facing teams. + +Two alternatives avoid standing up a separate team: + +- [Guest accounts](/administration-guide/onboard/guest-accounts) restrict an external user to the specific channels and teams they're invited to. They can't browse the channel directory or join channels on their own. Guest accounts fit when your external collaborators don't run Mattermost themselves and the scope of collaboration is limited. +- [Connected workspaces](/administration-guide/onboard/connected-workspaces) let users on separate Mattermost servers share channels without either organization exposing its internal workspace. This is the preferred model when your partners also run Mattermost, or when your compliance posture requires that external users are never provisioned on your server. + +## Establish a channel taxonomy + +Within each team, channels carry the organizational structure. A consistent taxonomy — a defined set of channel types, naming conventions, and sidebar categories — is what lets people navigate a large workspace without training. + +### Channel naming conventions + +Consistent channel names are what make the taxonomy navigable at scale. For the product rules that constrain any name, such as length limits and allowed characters, see [create channels](/end-user-guide/collaborate/create-channels#channel-name-rules). + +Good naming carries a team to several thousand channels without significant confusion. Every organization eventually hits a limit where an additional team is the better answer, but clear, short names postpone that point considerably. + +#### Start broad, then narrow + +It's natural to begin with broadly defined channels and let them divide as discussion grows. A single "Marketing" channel might become "Marketing-Website", "Marketing-Social-Media", and "Marketing-General". As the organization grows, disciplines split across business units, products, and geographies, producing names like "US-Marketing" and "UK-Marketing". + +Hierarchies combine into formats like `[SUB-TEAM]-[TOPIC]-[SUB-TOPIC]`, giving names such as `US-Mrkt-Website` and `UK-Mrkt-Social-Media`. + + + +Pick one separator and use it consistently. Common separators include `-`, `:`, `|`, and `>`. + + + +Shorten words, particularly category names, by removing vowels, word endings, and redundant letter sounds. "Marketing" becomes "Mrkt" and "Project" becomes "Prjt". For countries, use standard [2-letter country codes](https://www.nationsonline.org/oneworld/country_code_list.htm). + +#### Group related channels with a shared prefix + +Channels that belong together should share a prefix, such as `ops-`, `proj-`, `inc-`, or `social-`. Shared prefixes group related channels in search results and in [Find channel](/end-user-guide/collaborate/navigate-between-channels), so typing the prefix surfaces the whole set. + +![Browsing channels filtered by the ops- prefix to find related operational channels.](/images/workspace-org-browse-channels-prefix.png) + +Prefer descriptive names over abbreviations for channels that new users and external collaborators will encounter. Abbreviations are efficient once someone knows the system and opaque before then. Reserve them for conventions that are standard and documented. + +#### Prefix names with emojis + +Emoji prefixes are a lightweight way to make a long channel list scannable, and they work alongside text prefixes rather than replacing them. Using the same emoji across every channel in a category reinforces that grouping visually, so people locate the channel they need at a glance instead of reading the whole sidebar. + +The payoff is largest in big workspaces and during onboarding. New members infer what a channel is for from its prefix without a written explanation, which reduces the time spent teaching people how the workspace is arranged. + +For the steps to insert one, see [add an emoji to a channel name](/end-user-guide/collaborate/create-channels#add-an-emoji-to-a-channel-name). + +#### Common channel patterns + +Most workspaces end up with some mix of the following: + +- **Topic channels** organize broad subject areas, much like folders for email or documents. Examples: `Recruiting`, `Interviews`, `Legal-Reviews`, `Documentation`. As the channel count grows, name topics in a hierarchy so related ones sort together: `Legal-Trademarks`, `Legal-Contracts`, `Legal-Licensing`. +- **Announcement channels** broadcast from leadership or operations. Restrict posting to admins or designated roles by making them [read-only](/administration-guide/onboard/advanced-permissions#read-only-channels), so people receive the information without generating reply noise. Examples: `Town-Square`, `Announcements`, `Security-Advisories`. +- **Meeting channels** organize recurring meetings, where members post agenda items ahead of the meeting time. Examples: `Monday-Sales-Update`, `All-Hands-Meeting`. Number agenda items using [Markdown formatting](/end-user-guide/collaborate/format-messages#use-markdown), discuss each item in its own [thread](/end-user-guide/collaborate/organize-conversations#start-or-reply-to-threads) before and after the meeting, and keep the conferencing link in the [channel header](/end-user-guide/collaborate/channel-header-purpose#channel-header) so attendees can join from the channel. +- **Sub-team channels** gather a discipline, a project team, or a manager's reports. Examples: `Developers`, `Marketers`, `Offsite-Organizing-Committee`. These subdivide as they outgrow a single channel, into `US-Developers` and `UK-Developers`. +- **Project channels** are scoped to a specific outcome and are often private and time-bounded. Examples: `Logo-Design`, `Localization`, `Product-Launch`. Detailed work happens here, and summaries flow back to the larger channel the project came from. +- **Location channels** help people in the same building, city, or region coordinate meetings and events. Examples: `Loc-Building-10`, `Loc-Palo-Alto`, `Loc-Toronto`. They keep location-specific announcements out of everyone else's sidebar. +- **Integration channels** receive automated posts from bots, webhooks, monitoring systems, ticketing systems, and news alerts. Examples: `Bugs`, `Support-Tickets`, `News-Mentions`. Some people read these like a daily newspaper; others configure them to notify only on a mention or keyword. + +#### Systematic and automated names + +Some organizations, particularly in defense, operations, and incident response, create channels programmatically when an event occurs: a mission is activated, an incident is declared, a project opens in a tracking system. + +For automated creation, embed structured metadata in the name using a consistent format such as `[type]-[identifier]-[scope]`: + +- `ops-msl-2047-eglin` for a mission channel keyed to a mission number and location +- `inc-p1-20260819-db-outage` for a priority 1 incident keyed to date and component +- `proj-atlas-q3-frontend` for a project workstream + +A few principles make generated names durable: + +- Put the type prefix first so channels sort meaningfully in lists and search results. +- Embed the identifier used by the authoritative system, such as a mission number or ticket ID, so the channel maps cleanly to that record. +- Include enough context that someone encountering the channel for the first time understands its scope without opening it. +- Add a date only when it's meaningful. Don't date-stamp channels intended to be long-lived. + + + +Where a channel should exist only for the life of a run, [playbooks](/end-user-guide/workflow-automation/learn-about-playbooks) can create channels automatically. Completed run channels are not archived automatically, so archive them when they are no longer needed. See the [run channel behavior](/end-user-guide/workflow-automation/work-with-runs#runs-and-channel-behavior) guidance. Configure a channel name template on the playbook so each [run](/end-user-guide/workflow-automation/work-with-playbooks#actions) starts with a consistently named channel. + + + +### Organize the sidebar + +Channel names tell people what a channel is about. Categories tell them where to find it. In a well-organized workspace, a sidebar has four to six categories rather than a flat list of dozens of channels. + +![An operations workspace using shared channel prefixes and sidebar categories to keep channels discoverable.](/images/workspace-org-channel-taxonomy.png) + +A common starting structure: + +| Category | Contents | Example channels | +|---|---|---| +| Announcements | Read-only channels for organization-wide or team-wide broadcasts | `town-square`, `announcements`, `security-advisories`, `release-notices` | +| Operations | Ongoing operational work, incidents, and alerts | `ops-general`, `inc-p1-db-outage`, `alert-network` | +| Projects | Project-specific channels, often temporary | `proj-atlas-frontend`, `proj-pontoon-launch` | +| Integrations | Bot and automation channels | `jira-notifications`, `ci-alerts`, `pagerduty-feed`, `github-mattermost` | +| Social | Community, off-topic, and culture channels | `social-off-topic`, `social-palo-alto`, `social-running-club` | +| Reference | Low-traffic channels kept for reference rather than active work | `ref-docs-feedback`, `ref-archived-atlas` | + +Categories are personal to each user, so people can adapt them. Where [channel category sorting](/administration-guide/configure/experimental-configuration-settings#enable-channel-category-sorting) is enabled, channel admins can set a default category when [creating a channel](/end-user-guide/collaborate/create-channels). New members then arrive to an organized sidebar instead of building one themselves. + +See [customize your channel sidebar](/end-user-guide/preferences/customize-your-channel-sidebar) for how people manage categories day to day. + +### Manage notification load + +Structure also affects notification volume. Someone in 50 active channels across 10 teams hears from all of them unless they configure each one, and most people never do. The result is that they mute everything, miss what matters, and disengage. + +Naming and structure decisions can reduce that load by design: + +- Group high-volume, low-urgency channels such as bot feeds and CI alerts into one category, and set that category to mentions-only. Anyone who wants full notifications opts in. +- Use read-only announcement channels for broadcasts, so people receive the message without a stream of replies. +- Prefer threads over new channels for sub-conversations. One channel with active threads is easier to follow than several short-lived channels, each with its own notification stream. +- Weigh the notification cost when deciding between a new team and a new channel. Every team someone joins adds to their notification surface; a channel in a team they already belong to adds far less. + +See [channel notification preferences](/end-user-guide/preferences/manage-your-channel-specific-notifications) for the per-channel settings people control themselves. + +### Document your conventions + +Publish your naming and organization guide where people will find it, such as a pinned message in Town Square or your internal handbook. People who understand the conventions organize themselves. People who don't will create channels that break the system. + +## Enforce permissions + +Permissions turn your structure from a convention into a boundary the server enforces. That includes who can create teams and channels — naming conventions only hold when creation is managed. + +As a starting point for enterprise deployments: + +- **Team creation:** system admins only. Creating a team is a structural decision that deserves deliberate authorization. +- **Public channel creation:** team admins. Restricting this to system admins creates a bottleneck; opening it to everyone invites sprawl. +- **Private channel creation:** all members. Private channels aren't visible to others and tend to be self-limiting. +- **Channel deletion and archiving:** channel admins and system admins. + +Configure these in **System Console \> User Management \> Permissions**. See [advanced permissions](/administration-guide/onboard/advanced-permissions) for the full permission model and worked examples. + +Most organizations land on one of these channel-creation models: + +| Model | How it works | Best for | +|---|---|---| +| Open creation | Any member creates channels. Conventions are guidance, corrected retroactively. | Smaller organizations with an existing open-creation culture. | +| Team-admin creation | Creation is restricted to team admins (and system admins). | Enterprises that want structure without an IT bottleneck. | +| Request and approve | Users submit a request; on approval an admin creates the channel — or an automation creates it — with the agreed name, category, and membership. | Organizations needing an audit trail for channel creation, or highly regulated environments. | + +Team-admin creation is the most common choice in enterprise deployments, because it keeps naming standards intact without making people wait on system admins. To set it up, turn off **Create Channels** for All Members and leave it on for Team Administrators. See [restrict who can create channels in specific teams](/administration-guide/onboard/advanced-permissions#restrict-who-can-create-channels-in-specific-teams). + +Mattermost doesn't ship a channel request workflow. Many organizations handle requests through a form, ticket system, or other intake process people already use, then have an admin create the channel. You can also automate approval with the [plugin framework](https://developers.mattermost.com/integrate/plugins/) and the [channel creation API](https://api.mattermost.com/#tag/channels/operation/CreateChannel), so an approved request produces a correctly named channel without manual admin work. + +In larger deployments, [attribute-based access control](/administration-guide/manage/admin/attribute-based-access-control) ties team and channel membership to attributes from your identity provider. People are added to the right teams as they join, and lose access when their attributes change. Without it, keeping membership correct across many teams becomes a significant administrative burden. + +## Iterate as you scale + +Workspace organization isn't a one-time decision. Review your configuration when you see any of the following: + +- **Team or channel count has grown sharply.** If either has more than doubled since your last review, audit for sprawl, archive what's inactive, and confirm your creation permissions are still right. +- **People report they can't find channels.** Your naming conventions either aren't working or aren't being followed. +- **Notification complaints increase.** Usually a sign that categories aren't being used, that high-volume integration channels aren't muted, or that team structure is duplicating notification streams. +- **A new population joins with different security requirements.** A new subsidiary, partner organization, or classification level is the most common trigger for a structural review. +- **You adopt attribute-based access control or change identity providers.** A change in identity infrastructure is an opportunity to automate membership that was previously manual. diff --git a/docs/main/administration-guide/onboard/advanced-permissions.mdx b/docs/main/administration-guide/onboard/advanced-permissions.mdx index 96a553bdbc8..deaed552ac3 100644 --- a/docs/main/administration-guide/onboard/advanced-permissions.mdx +++ b/docs/main/administration-guide/onboard/advanced-permissions.mdx @@ -35,7 +35,7 @@ You can access the System Scheme interface by going to **System Console \> User -On systems with multiple [Mattermost teams](/end-user-guide/collaborate/organize-using-teams#single-team-versus-multiple-teams), each team may operate and collaborate in a unique way. Team Override Schemes give Admins the flexibility to tailor permissions to the needs of each team. +On systems with multiple [Mattermost teams](/end-user-guide/collaborate/organize-using-teams#team-structure), each team may operate and collaborate in a unique way. Team Override Schemes give Admins the flexibility to tailor permissions to the needs of each team. When you use this permission scheme: diff --git a/docs/main/administration-guide/upgrade/enterprise-roll-out-checklist.mdx b/docs/main/administration-guide/upgrade/enterprise-roll-out-checklist.mdx index aaf6575cc66..d48c048dc43 100644 --- a/docs/main/administration-guide/upgrade/enterprise-roll-out-checklist.mdx +++ b/docs/main/administration-guide/upgrade/enterprise-roll-out-checklist.mdx @@ -214,7 +214,7 @@ Now that you have an environment in place, we recommend working through the foll - Determine and create a team structure for your environment > - Recommendation: Start with fewer teams in your early roll out -> - Resource: [https://docs.mattermost.com/end-user-guide/collaborate/channel-naming-conventions.html](https://docs.mattermost.com/end-user-guide/collaborate/channel-naming-conventions.html) +> - Resource: [https://docs.mattermost.com/administration-guide/manage/admin/workspace-organization.html](https://docs.mattermost.com/administration-guide/manage/admin/workspace-organization.html) - Determine and create key channels to support your users. A default Town Square channel is created automatically and available on every team. diff --git a/docs/main/end-user-guide/collaborate/channel-header-purpose.mdx b/docs/main/end-user-guide/collaborate/channel-header-purpose.mdx index 1785cfd872d..a4beb2fae5a 100644 --- a/docs/main/end-user-guide/collaborate/channel-header-purpose.mdx +++ b/docs/main/end-user-guide/collaborate/channel-header-purpose.mdx @@ -15,7 +15,7 @@ Every channel in Mattermost serves a purpose and exists for a reason. You can co ## Channel name -You're prompted to provide a channel name when [creating a new channel in Mattermost](/end-user-guide/collaborate/create-channels). Channel names must be at least 2 characters, and can be up to 64 characters in length. See the [channel naming conventions](/end-user-guide/collaborate/channel-naming-conventions) documentation for additional details and guidance on why channel naming is important. +You're prompted to provide a channel name when [creating a new channel in Mattermost](/end-user-guide/collaborate/create-channels). Channel names must be at least 2 characters, and can be up to 64 characters in length. See the [channel name rules](/end-user-guide/collaborate/create-channels#channel-name-rules) for details, and the [workspace organization](/administration-guide/manage/admin/workspace-organization#channel-naming-conventions) documentation for guidance on naming channels consistently across your organization. diff --git a/docs/main/end-user-guide/collaborate/channel-naming-conventions.mdx b/docs/main/end-user-guide/collaborate/channel-naming-conventions.mdx deleted file mode 100644 index 52d92610a2d..00000000000 --- a/docs/main/end-user-guide/collaborate/channel-naming-conventions.mdx +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: "Channel naming conventions" ---- - - -All organizations are different and have different communication needs. The importance of organizing your conversations increases as your user base grows. The following are ideas for how you might want to name, group, and structure your channels. If you change your mind about a channel's name, you can [rename it](/end-user-guide/collaborate/rename-channels). - -## Basic structure - -- Channel names appear in menus where users select which conversations to join. -- Channel names are unique. -- Channel names have a 64-character limit to ensure readability on both desktop and mobile devices. -- An additional 1024 characters are available for describing the channel's focus in the channel header and channel information pane. -- An additional 128 characters are available for a **Channel Purpose** that's visible in the channel header and the channel information pane. -- Channel names can include standard Unicode emojis that are universally supported emojis that look the same (or similar) across platforms. Specify a Unicode emoji by positioning your cursor in the channel **Display Name** field and accessing the Unicode emoji picker for your operating system, as follows: - -> - On Windows press Windows + . or ; to open the Unicode emoji picker. -> - On macOS, press Ctrl + ⌘ + Space to open the Unicode emoji picker. - -We recommend prefixing channel names with emojis for the following reasons: - -> - Emojis can make it easier for users to quickly identify and manage channels, particularly in large workspaces with many channels. -> - Sharing the same emoji across channels related to a specific category or function helps maintain organization and consistency across the workspace. -> - Making channels more visually distinct with emojis helps users find the channels they need more quickly and easily at a glance, reducing the time spent searching for the right channel. -> - New users can quickly understand the purpose of various channels based on their emoji prefixes without needing extensive explanations. -> - As users grasp channel structure through emojis, the time and effort needed to train new members on navigating the workspace is reduced. -> - A well-organized and visually appealing workspace can encourage users to participate more actively, which can lead to more effective communication and collaboration. - -## Scope channel names - -It's natural to start with broadly defined channels and let them divide into narrower topics as discussions progress. - -For example, you might begin with a general "Marketing" channel. As conversations progress, you might divide that channel into: "Marketing: Website", "Marketing: Social Media", "Marketing: General". - - - -Use colons to separate sections of channel names, rather than `-` or `>` which require more spaces to display. - - - -As the organization grows, disciplines might split across business units, products and geographies, with channel names like "US: Marketing" and "UK: Marketing". - - - -If you need to shorten country names, use standard [2-letter country codes](https://www.nationsonline.org/oneworld/country_code_list.htm). - - - -You can combine the hierarchies, with formats like `[SUB-TEAM]: [TOPIC]: [SUB-TOPIC]`. For example: `US: Mrkt: Website` and `UK: Mrkt: Social Media`. - - - -Shorten words, particularly categories, by removing vowels, endings, and redundant letter sounds. Example: Turn "Marketing" into "Mrkt", and "Project" into "Prjt". - - - -Good naming can take a team up to several thousand channels without significant confusion. Eventually every organization hits a limit and an additional team might need to be created on the server to accommodate the large number of channels. Keeping names clear and short lets users navigate large collections of channels quickly. - -Here are different navigation options and types of channels to consider. - -### Navigate channels using the keyboard - -Keyboard shortcuts allow users to jump between channels. See the [keyboard shortcuts](/end-user-guide/collaborate/keyboard-shortcuts) documentation for all available keyboard shortcuts. - -### Topic channels - -Topics are broad categories for organizing discussions. Topics are similar to how a user might create a folder for organizing emails or documents. Examples: Recruiting, Interviews, Legal Reviews, Documentation. - -Users can join and leave topic-based channels, as well as add colleagues to have topic-based discussions. - -As teams get larger and the number of channels increase, you may start naming topics in a hierarchy to make them easier to find. Examples: Legal: Trademarks, Legal: Contracts, Legal: Licensing. - -### Meeting channels - -Meeting channels are often used to organize regular meetings. Members can add topics as messages to be discussed during the regular meeting time. Examples: Monday Sales Update, All Hands Meeting. - -There are three built-in features to make meetings easier: - -1. Numbered agenda items in title text - -You can number and format messages as agenda items to discuss for the next meeting. - - - -Try pasting the following as an example in a channel designated for meetings: - - #### 1) Agenda item example - #### Commentary about agenda item to be discussed. - - - -2. Threaded messaging - -On an agenda item message, you can select `[...] > Reply` to leave comments about an agenda item before or after a meeting to extended discussion. - -3. Header links - -When meeting remotely, add persistent links to your video or audio conferencing solution, like Zoom, Google Hangouts, or BlueJeans in the channel header. See our [documentation](/end-user-guide/collaborate/channel-header-purpose) to learn more about working with channel headers. - -When it's time to meet, your team can select the conference link to connect. - -### Sub-team channels - -Sub-teams can include people from the same discipline, project teams, people with the same manager or other groups brought together for a shared purpose. Examples: Developers, Marketers, Offsite Organizing Committee, SusanK's Directs - -As sub-teams grow beyond a manageable size for one channel, they can sub-divide. Examples: US: Developers, UK: Developers, SusanK's Directs, SusanK's Extended Directs. - -### Project channels - -Project channels discuss how groups of people come together to achieve specific outcomes. Examples: Logo Design, Localization, Product Launch. - -Projects are often private channels rather than public channels and are used to organize a small team around a project brought up in a larger channel. The Project Channel is used to do detailed work, and updates are typically communicated back to larger channels. - -### Location channels - -If your teams are in different buildings, cities or regions, you can create Location channels to help people coordinate meetings and get-togethers. Examples: Building 10, Palo Alto, Toronto, Delaware. - -This helps share announcements and discussions relevant to only those locations. - -### Data channels - -Data channels allow automatic integration. Information like new or updated support tickets or bug reports, Twitter updates or mentions of your company name in the news can all be made available in channels your team chooses to monitor. There is a wide array of options. Examples: Bugs, Support Tickets, Twitter, News Mentions. - -People might use these channels like a daily newspaper, reading about everything that's happened in the last day, while other configurations allow notifications to alert only when their username or certain key words are mentioned. - -## Channel naming examples - -Here is an example of what a marketer's channels might look like in a small team: - -CHANNELS - -- Recruiting -- Interviews -- Marketing -- Sales -- All Hands Meeting -- Town Square -- Off-Topic - -PRIVATE CHANNELS - -- Website -- Twitter Marketing -- Logo Design - -DIRECT MESSAGES - -- \[Sales People\] -- \[Marketers\] -- \[Recruiter\] -- \[Manager\] - -Here's an example of what a marketer's channels might look like if she was working in the Palo Alto, California office of a large enterprise, working on a product called "Pontoon": - -CHANNELS - -- Geo: PA: Recruiting -- Geo: PA: Interviews -- US: Mrkt: General -- US: Sales: West Coast -- US: All Hands -- Town Square -- Off-Topic - -PRIVATE CHANNELS - -- Pontoon: Mkrt: Website -- Pontoon: Mkrt: Twitter -- Pontoon: Mkrt: Logo Design - -DIRECT MESSAGES - -- \[West Coast Sales People\] -- \[Marketing Peers\] -- \[Recruiter for PA office\] -- \[Manager\] diff --git a/docs/main/end-user-guide/collaborate/collaborate-within-channels.mdx b/docs/main/end-user-guide/collaborate/collaborate-within-channels.mdx index e466091f440..e3238d13d79 100644 --- a/docs/main/end-user-guide/collaborate/collaborate-within-channels.mdx +++ b/docs/main/end-user-guide/collaborate/collaborate-within-channels.mdx @@ -25,7 +25,6 @@ As your channel sidebar fills up with channels you've joined, you can organize y Learn more about collaborating within Mattermost channels: -- [Channel naming conventions](/end-user-guide/collaborate/channel-naming-conventions) - Learn why channel names are important. - [Communicate a channel's focus and scope](/end-user-guide/collaborate/channel-header-purpose) - Learn how to communicate a channel's scope and focus. - [Browse channels](/end-user-guide/collaborate/browse-channels) - Browse all available public channels you can join, and all channels you're a member of. - [Join and leave channels](/end-user-guide/collaborate/join-leave-channels) - Learn how to start or stop being a channel member. diff --git a/docs/main/end-user-guide/collaborate/create-channels.mdx b/docs/main/end-user-guide/collaborate/create-channels.mdx index 4524a5bed71..231f2cb2728 100644 --- a/docs/main/end-user-guide/collaborate/create-channels.mdx +++ b/docs/main/end-user-guide/collaborate/create-channels.mdx @@ -63,6 +63,23 @@ Tap