لم تُترجم هذه الصفحة بعد.

Organizations and workspaces

This page is for anyone who works with other people on instruction.md, and for whoever sets up the team. An organization is your team: it holds the plan, the people and the rules. A workspace is a place inside it where instructions are kept.

The organization owns the plan, people and rules; workspaces hold the instructions.

Your personal organization and team organizations

Every account comes with a Personal organization. It is yours alone, it has one workspace, and nobody else can join it. The menu at the top of the side bar says Just you under it.

To work with other people, make an organization of your own:

  1. Open the menu at the top of the side bar

    It shows your organization's name, and the workspace you are in under it.

  2. Choose New organization

    The New organization dialog asks for Its name, such as Acme. It may also ask for Its address, the short name that appears in your instructions' addresses.

  3. Choose Create organization

    The editor opens in the new organization. You are its owner, it starts on the free plan, and it has one workspace called General. You invite people from Settings ▸ People.

You can belong to several organizations. Each one has its own plan, people and rules. Nothing in one is shared with another unless someone shares it.

What belongs to the organization, and what belongs to a workspace

The organization owns everything that is about the team as a whole:

A workspace holds the work itself: instructions, and the projects and folders you sort them into. Each person can have a role of their own in each workspace.

The difference matters when you move things. Moving an instruction to another workspace changes who works on it. It does not change the plan or the rules, which stay with the organization.

Workspaces

Every organization has one workspace to start with, called General. It is marked Default in Settings ▸ Workspaces. A person's role in the default workspace is the role they start with in every other open workspace. That is why the default workspace is always open, and why it can't be deleted.

How many workspaces an organization can have depends on its plan:

Plans Community 1 · Pro 1 · Team unlimited · Enterprise unlimited

A personal organization always has one. On a plan with several, only the organization's owners and admins add them. If an organization moves to a plan with fewer, it keeps the workspaces it has, but can't add more.

A workspace is either open or restricted:

  • Open: every member of the organization sees it. Each member has the role they have in the default workspace, up to Maintainer, unless they are given a role of their own there. Administering a workspace is always given, never inherited. Guests and agents don't get a role this way: a guest sees only what is shared with them, and an agent works only in the workspaces it is added to.
  • Restricted: only the people added to it see it and its instructions. A lock shows next to its name.

The organization's owners and admins see every workspace, open or restricted. Instructions shared with Your organization can be read by everyone in it, whichever workspace holds them.

A third kind, a sealed workspace, keeps its instructions so that only the people you give the key to can read them. Sealed workspaces are in beta and not yet independently reviewed. They don't count toward the limit above. See Sealed workspaces.

The organization and workspace menu

The menu at the top of the side bar is where you change organization or workspace. Its title is Organizations and workspaces.

The organization and workspace menu.
  • In one organization, the menu shows its name, your role there, and its workspaces. The one you are in is highlighted. A restricted one has a lock.
  • In several organizations, the menu lists them under Organizations. Point at one, or press it, to see its workspaces.
  • The last row is New workspace in an organization's list, or New organization in the list of organizations.

New workspace is greyed out when adding one would do nothing. In the menu, a screen reader says why. In Settings ▸ Workspaces, the reason shows under Add a workspace. The reasons are:

You see Why What to do
Personal has one workspace. Create an organization to have several. A personal organization keeps one workspace. Choose New organization.
Only the organization's owners and admins add workspaces Your role in the organization is member, billing or guest. Ask an owner or an admin.
More workspaces come with the Team plan The organization has as many workspaces as its plan allows. Upgrade in Settings ▸ Billing (Plans, limits and billing).

New organization is greyed out until you sign in.

Create, rename, restrict and delete a workspace

Who can do this: the organization's owners and admins. Everyone else can read the list in Settings ▸ Workspaces.

Plans Community 1 · Pro 1 · Team unlimited · Enterprise unlimited

  1. Open Settings ▸ Workspaces

    Each workspace has a section of its own. Its first line says how many instructions it holds, and who sees it: open to the organization, or restricted to a number of people.

  2. Add a workspace

    Under New workspace, type a name in Workspace name and choose Create. You can also choose New workspace in the side bar menu, then Create workspace. The new workspace is open, and you are its Admin.

  3. Rename it

    Change the name in its About row. It saves when you press Enter or leave the field.

  4. Restrict it, or open it again

    Turn on Restricted. The editor asks Restrict "…"? first, because everyone who wasn't added loses access, except to its instructions shared with Your organization and to what is shared with them. Choose Restrict. Turn it off to open it to the organization again. The default workspace has no Restricted switch.

  5. Choose who has a role there

    In its People row, choose Show. Change a person's role, choose Remove to take their role there away, or use Add someone to give a member of the organization a role. Guests can't be added to a workspace.

  6. Delete it

    Choose Delete workspace. Only an empty workspace can be deleted, and never the default one. Move or delete its instructions first. The editor asks before it deletes: its folders, its projects and what is in its trash go for good, and its people lose their roles there. Choose Delete the workspace. If something in its trash is under legal hold, it can't be deleted until the hold ends.

Rename the organization or change its address

Who can do this: the organization's owners and admins. A personal organization is named after you, and its address changes with your handle in Your account ▸ Profile.

An organization has two names, both in Settings ▸ People ▸ This organization:

  • Name is how its people, and the readers of its instructions, see it. Change it and it shows in the side bar at once.
  • URL name is the part of its instructions' addresses that names the organization, on the web and for agents. The editor asks Change the URL name to …? first. Choose Change it. Every address changes for people and for agents, and the old addresses keep leading to the new ones for good. The editor then opens again under the new name.

A URL name is 1 to 64 lowercase letters, digits and single hyphens, and it can't start or end with a hyphen. Some words are kept by instruction.md and can't be used. The editor says so before anything changes.

Delete the organization

Who can do this: an owner. The row is in Settings ▸ People ▸ Delete this organization.

  1. Choose Delete… next to Delete it, and everything in it

    The editor shows what will happen, in numbers: how many instructions go, how many people lose access, how many agents stop, and how long its address stays taken.

  2. Choose Delete the organization

    Its instructions, their versions and history, and its workspaces are deleted for good. Its agents stop at once, and agents following its instructions get nothing new. An export of the organization is made for you first. The editor then opens your own organization.

Some organizations can't be deleted here:

  • A personal organization goes only with your account. See Your data: privacy switches, download, delete.
  • An Enterprise organization is closed with us, not in the editor. Write to us at support.
  • An organization under legal hold can't be deleted until the hold ends. The editor says "this organization is under legal hold and can't be deleted".

Common misunderstandings

  • "A workspace has its own plan." It doesn't. The plan, the bill and the seats belong to the organization, and every workspace shares them.
  • "Restricting a workspace hides all of its instructions." Instructions shared with Your organization stay readable by the whole organization. Restricting decides who works in the workspace, not who can read those instructions.
  • "Changing the URL name breaks my agents." It doesn't. The old addresses keep leading to the new ones.
  • "Owners need a role in every workspace." They don't. The organization's owners and admins manage every workspace already.

Questions

What is the difference between an organization and a workspace?

The organization is the team: it holds the plan, the bill, the people, the rules, the apps and the keys. A workspace is a place inside it that holds instructions, projects and folders. One organization can have several workspaces, depending on its plan.

Why is New workspace greyed out?

Either you are in your personal organization, which keeps one workspace, or you aren't an owner or an admin, or the organization has as many workspaces as its plan allows. A screen reader says which. See the table under The organization and workspace menu.

Can I delete the General workspace?

No. The default workspace can't be deleted or restricted, because it is where every member's starting role is kept. You can rename it.

Who can see a restricted workspace?

The people added to it, and the organization's owners and admins. Everyone else can still read its instructions shared with Your organization, and anything shared with them directly.

Every instruction gets a new address, and the old addresses keep leading to the new ones for good. People and agents using the old address are not cut off.

For developers: every setting and its path are listed in the settings map.

Last checked against the product:

Was this page helpful? Report a problem