docker · sarahsanders-docker · Jul 7, 2025 · Jul 1, 2025 · Jul 1, 2025 · Jul 7, 2025
diff --git a/content/includes/admin-org-overview.md b/content/includes/admin-org-overview.md
@@ -1,6 +1,6 @@
 ---
 title: Administration
-description: Discover manuals on administration for accounts, organizations, and companies.
+description: Overview of administration features and roles in the Docker Admin Console
 keywords: admin, administration, company, organization, Admin Console, user accounts, account management
 weight: 10
 params:
@@ -35,17 +35,66 @@
 - /docker-hub/admin-overview
 ---
 
-Administrators can manage companies and organizations using the Docker Admin Console.
+Administrators can manage companies and organizations using the
+[Docker Admin Console](https://app.docker.com/admin). The Admin Console
+provides centralized observability, access management, and security controls
+across Docker environments.
+
+## Company and organization hierarchy
 
 The [Docker Admin Console](https://app.docker.com/admin) provides administrators with centralized observability, access management, and controls for their company and organizations. To provide these features, Docker uses the following hierarchy and roles.
 
-![Docker hierarchy](./images/docker-admin-structure.webp)
+![Diagram showing Docker’s administration hierarchy with Company at the top, followed by Organizations, Teams, and Members](./images/docker-admin-structure.webp)
+
+### Company
+
+A company groups multiple Docker organizations for centralized configuration.
+Companies are only available for Docker Business subscribers.
+
+Companies have the following administrator role available:
+
+- Company owner: Can view and manage all organizations within the company.
+Has full access to company-wide settings and inherits the same permissions as
+organization owners.
+
+### Organization
+
+An organization contains teams and repositories. All Docker Team and Business
+subscribers must have at least one organization.
+
+Organizations have the following administrator role available:
+
+- Organization owner: Can manage organization settings, users, and access
+controls.
+
+### Team
+
+Teams are optional and let you group members to assign repository permissions
+collectively. Teams simplify permission management across projects
+or functions.
+
+### Member
+
+A member is any Docker user added to an organization. Organization and company
+owners can assign roles to members to define their level of access.
+
+> [!NOTE]
+>
+> Creating a company is optional, but organizations are required for Team and
+Business subscriptions.
+
+## Admin Console features
+
+Docker's [Admin Console](https://app.docker.com/admin) allows you to:
+
+- Create and manage companies and organizations
+- Assign roles and permissions to members
+- Group members into teams to manage access by project or role
+- Set company-wide policies, including SCIM provisioning and security
+enforcement
+
+## Manage companies and organizations
 
-- Company: A company simplifies the management of Docker organizations and settings. Creating a company is optional and only available to Docker Business subscribers.
-  - Company owner: A company can have multiple owners. Company owners have company-wide observability and can manage company-wide settings that apply to all associated organizations. In addition, company owners have the same access as organization owners for all associated organizations.
-- Organization: An organization is a collection of teams and repositories. Docker Team and Business subscribers must have at least one organization.
-  - Organization owner: An organization can have multiple owners. Organization owners have observability into their organization and can manage its users and settings.
-- Team: A team is a group of Docker members that belong to an organization. Organization and company owners can group members into additional teams to configure repository permissions on a per-team basis. Using teams to group members is optional.
-- Member: A member is a Docker user that's a member of an organization. Organization and company owners can assign roles to members to define their permissions.
+Learn how to manage companies and organizations in the following sections.
 
 {{< grid >}}
@@ -2,8 +2,8 @@
 title: Organization administration overview
 linkTitle: Organization administration
 weight: 10
-description: Learn about managing organizations in Docker including how they relate to teams, how to onboard, and more
-keywords: organizations, admin, overview
+description: Learn how to manage your Docker organization, including teams, members, permissions, and settings.
+keywords: organizations, admin, overview, manage teams, roles
 grid:
 - title: Onboard your organization
   description: Learn how to onboard and secure your organization.
@@ -45,10 +45,26 @@
   icon: help
 ---
 
-{{% include "admin-org-overview.md" %}}
+A Docker organization is a collection of teams and repositories with centralized
+management. It helps administrators group members and assign access in a
+streamlined, scalable way.
 
-To create an organization, see [Create your organization](../organization/orgs.md).
+## Organization structure
 
-Learn how to administer an organization in the following sections.
+The following diagram shows how organizations relate to teams and members.
 
-{{< grid >}}
+![Diagram showing how teams and members relate within a Docker organization](/admin/images/org-structure.webp)
+
+## Organization members
+
+Organization owners have full administrator access to manage members, roles,
+and teams across the organization.
+
+An organization includes members and optional teams. Teams help group members
+and simplify permission management.
+
+## Create and manage your organization
+
+Learn how to create and manage your organization in the following sections.
+
+{{< grid >}}
@@ -9,13 +9,15 @@ aliases:
 
 {{< summary-bar feature_name="Admin orgs" >}}
 
-You can convert an existing user account to an organization. This is useful if you need multiple users to access your account and the repositories that it’s connected to. Converting it to an organization gives you better control over permissions for these users through [teams](manage-a-team.md) and [roles](roles-and-permissions.md).
+Learn how to convert an existing user account into an organization. This is
+useful if you need multiple users to access your account and the repositories
+it’s connected to. Converting it to an organization gives you better control
+over permissions for these users through
+[teams](/manuals/admin/organization/manage-a-team.md) and
+[roles](/manuals/security/for-admins/roles-and-permissions.md).
 
-When you convert a user account to an organization, the account is migrated to a Docker Team subscription.
-
-> [!IMPORTANT]
->
-> Once you convert your account to an organization, you can’t revert it to a user account.
+When you convert a user account to an organization, the account is migrated to
+a Docker Team subscription by default.
 
 ## Prerequisites
 
@@ -34,40 +36,43 @@ Before you convert a user account to an organization, ensure that you meet the f
 
     If you want to convert your user account into an organization account and you don't have any other user accounts, you need to create a new user account to assign it as the owner of the new organization. With the owner role assigned, this user account has full administrative access to configure and manage the organization. You can assign more users the owner role after the conversion.
 
-## Effects of converting an account into an organization
-
-Consider the following effects of converting your account:
-
-- This process removes the email address for the account, and organization owners will receive notification emails instead. You'll be able to reuse the removed email address for another account after converting.
-
-- The current subscription will cancel and your new subscription will start.
-
-- Repository namespaces and names won't change, but converting your account removes any repository collaborators. Once you convert the account, you'll need to add those users as team members.
-
-- Existing automated builds will appear as if they were set up by the first owner added to the organization. See [Convert an account into an organization](#convert-an-account-into-an-organization) for steps on adding the first owner.
-
-- The user account that you add as the first owner will have full administrative access to configure and manage the organization.
-
-- To transfer a user's personal access tokens (PATs) to your converted organization,
-you must designate the user as an organization owner. This will ensure any PATs associated with the user's account are transferred to the organization owner.
-
-> [!TIP]
->
-> To avoid potentially disrupting service of personal access tokens when converting an account or changing ownership, it is recommended to use [organization access tokens](/manuals/security/for-admins/access-tokens.md). Organization access tokens are
-associated with an organization, not a single user account.
+## What happens when you convert your account
+
+The following happens when you convert your account into
+an organization:
+
+- This process removes the email address for the account. Notifications are
+instead sent to organization owners. You'll be able to reuse the
+removed email address for another account after converting.
+- The current subscription will automatically cancel and your new subscription
+will start.
+- Repository namespaces and names won't change, but converting your account
+removes any repository collaborators. Once you convert the account, you'll need
+to add repository collaborators as team members.
+- Existing automated builds appear as if they were set up by the first owner
+added to the organization.
+- The user account that you add as the first owner will have full
+administrative access to configure and manage the organization.
+- To transfer a user's personal access tokens (PATs) to your converted
+organization, you must designate the user as an organization owner. This will
+ensure any PATs associated with the user's account are transferred to the
+organization owner.
 
 ## Convert an account into an organization
 
-Before you convert an account into an organization ensure you have:
-
-- Removed your user account from any company or teams or organizations
-- Created a new Docker ID before you convert an account
-
-See the [Prerequisites](#prerequisites) section for details.
-
-1. Sign in to [Docker Home](https://app.docker.com/login).
-1. Select your avatar in the top-right corner and select **Account settings**.
-1. In the **Settings** section, select **Convert**.
-1. Review the warning displayed about converting a user account. This action cannot be undone and has considerable implications for your assets and the account.
-1. Enter a **Username of new owner** to set an organization owner. This is the user account that will manage the organization, and the only way to access the organization settings after conversion. You cannot use the same Docker ID as the account you are trying to convert.
-1. Select **Confirm**. The new owner receives a notification email. Use that owner account to sign in and manage the new organization.
+> [!IMPORTANT]
+>
+> Converting an account into an organization is permanent. Back up any data
+ or settings you want to retain.
+
+1. Sign in to [Docker Home](https://app.docker.com/).
+1. Select your avatar in the top-right corner to open the drop-down.
+1. From **Account settings**, select **Convert**.
+1. Review the warning displayed about converting a user account. This action
+cannot be undone and has considerable implications for your assets and the
+account.
+1. Enter a **Username of new owner** to set an organization owner. The new
+Docker ID you specify becomes the organization’s owner. You cannot use the
+same Docker ID as the account you are trying to convert.
+1. Select **Confirm**. The new owner receives a notification email. Use that
+owner account to sign in and manage the new organization.