Merge pull request #573 from zihanKuang/org-team-issue

 Docs: Refactor and Enhance Organization and User Management Documentation

Author: zihanKuang

content/en/cloud/identity/organizations/_index.md

@@ -5,21 +5,9 @@ description: >
 categories: [Identity]
 tags: [orgs]
 ---
-<div style="display:flex; align-items: start;flex-direction: row;flex: 1 1 auto; ">
-  <div style="flex-direction: column;">
-    <p>
-    Organizations are the basic unit of multi-tenancy inside of Layer5 Cloud. Organizations can have any number of teams. Teams can have any number of users. Users can belong to any number of teams. Users may belong to any number of organizations.
-    </p>
-    <p>
-    Outside of grouping users together, teams offer control access to workspaces and to workspace resources such as environments and managed and unmanaged connections
-    </p>
-  </div>
-  <div style="flex-direction: column;min-width: 50%;justify-items: center;margin-left:1rem;">
-    <h4 style="text-align:center;font-weight:bold;">Organizational Hierarchy</h4>
-    <img
-      src="/cloud/identity/images/organization_units.svg"
-      link="images/organization_units.svg"
-      alt="Organizational units"
-      width="auto" />
-  </div>
-</div>
+
+Organizations are the basic unit of multi-tenancy inside of Layer5 Cloud. Organizations can have any number of teams. Teams can have any number of users. Users can belong to any number of teams. Users may belong to any number of organizations.
+
+Outside of grouping users together, teams offer control access to workspaces and to workspace resources such as environments and managed and unmanaged connections
+
+<img src="/cloud/identity/images/organization_units.svg" alt="Organizational units" style="width: 35%;" />

content/en/cloud/identity/organizations/org-management/create_org.png

@@ -0,0 +1,116 @@
+---
+title: Organization Management
+description: >
+    Create, edit, invite members to, and delete your Organizations within Layer5 Cloud.
+weight: 1
+categories: [Identity]
+tags: [orgs]
+---
+
+This guide covers creating new organizations, editing their details, inviting members, and deleting organizations when necessary.
+
+![Organization Overview](/cloud/identity/organizations/org-management/org_overview.png)
+
+{{< alert title="Permissions Required" type="info" >}}
+Operations described on this page for managing your Organization typically require Organization Administrator or similar administrative roles. To understand the specific roles needed for each action, please refer to the [Default Permissions reference](https://docs.layer5.io/cloud/reference/default-permissions/).
+{{< /alert >}}
+
+## Creating an Organization
+
+An Organization provides a way to structure your teams, users, and resource access for different projects or initiatives.
+
+### How to create an Organization
+
+1.  Go to the Organizations section, click the **Add Organization** button
+2.  The "Create New Organization" modal will appear:
+    -   Organization Name: Enter a unique name for your new Organization. This is a required field.
+    -   Country (Optional): Select the country for your Organization.
+    -   Region (Optional): Choose the time zone for your Organization.
+    -   Add Organization Members (Optional): You can begin adding **existing** Layer5 Cloud users to your new Organization in this field.
+
+<img src="/cloud/identity/organizations/org-management/create_org.png" alt="Filling out new Organization details" style="width: 30%;" />
+
+{{< alert type="info" title="Unable to Create More Organizations?" >}}
+If the "Add Organization" button is disabled, it means your current role does not permit creating additional Organizations. Only users with roles like Organization Administrator or Provider Administrator can create new Organizations.
+{{< /alert >}}
+
+## Editing Your Organization
+
+You can update your Organization's name, location, associated teams, branding, and access its invitation link by editing its details.
+
+### How to Edit Your Organization
+
+1.  Select the Organization you want to modify and click its **"Edit"** button.
+2.  The "Edit Organization" model will open:
+    -   Add Team: Associate existing Teams with this Organization.
+    -   Theme: Customize your Organization's visual theme by selecting from the available color swatches.
+    -   Logos: Upload specific logo versions for various display contexts by clicking the respective **"Upload"** buttons.
+    -   Invitations: Access a shareable link to invite users to your Organization.
+
+<img src="/cloud/identity/organizations/org-management/edit_org.png" alt="Editing Organization Details" style="width: 30%;" />
+
+## Using the Open Organization Invitation Link
+
+To invite multiple users to your organization at once, or to allow open sign-ups (for example, for a public community), you can use the "Open Organization Invitation Link." This is a shareable link that lets users join directly.
+
+### When to Use This Link
+* Bulk Onboarding: To quickly onboard many users without sending individual emails.
+* Public Sign-ups: To let people sign up openly, for instance, by posting the link on a community page or another public resource.
+* Cross-Organizational Collaboration: To make it easy for collaborators from other organizations or external partners to join.
+
+![Obtain Organization Invite Link](/cloud/identity/organizations/org-management/org_open_invite.gif)
+
+{{< alert title="Inviting Users to Specific Teams" type="info" >}}
+If you want to invite users directly to a specific team within your organization, please refer to the documentation on [Open Team Invites](https://docs.layer5.io/cloud/identity/teams/)
+{{< /alert >}}
+
+### How it Works
+
+-  For New Users (without an existing Layer5 Cloud account):
+    * When a new user clicks the invitation link, they will be directed to the sign-up page.
+    * After creating their account, they will be automatically added to the organization associated with the invite link.
+
+-  For Existing Users (with a Layer5 Cloud account):
+    * An existing user who clicks the invitation link will be able to join the organization using their current account.[^1]
+
+## Deleting Your Organization
+
+Deleting an Organization is a permanent action that removes it entirely, including all associated teams, user memberships within that Organization, and its resources. 
+
+{{< alert type="warning" title="Deletion is Permanent and Unrecoverable" >}}
+Once an Organization is deleted, **this action cannot be undone**.
+{{< /alert >}}
+
+### Consequences of Deletion
+
+Upon confirming deletion, the following are **permanently and irretrievably removed**:
+* The Organization Itself: Including all its unique settings and configurations.
+* All Associated Teams: All teams belonging to this Organization.
+* User Access to this Organization: Users' memberships, roles, and permissions specific to this Organization are revoked. (Note: Users' individual accounts themselves are not deleted from the system).
+* Owned Workspaces: All Workspaces belonging to this Organization.
+* Designs and Environments: All Designs and Environments within the Organization's deleted Workspaces will also be permanently removed.
+
+### When NOT to Delete
+Avoid deleting an Organization if:
+* You might need the Organization or its data later.
+* Critical resources within it have not been backed up or migrated.
+* Other users or services still depend on it.
+* You only need to modify memberships or restructure parts of it.
+* You are unsure about the full extent of its data or dependencies.
+
+### When Deletion May Be Appropriate
+
+* The Organization was for a temporary project or test and is no longer needed.
+* It was created in error or is now redundant due to consolidation.
+* Permanent removal of all its data is required for compliance or data lifecycle management.
+* You are certain all its resources are obsolete or migrated, and no dependencies remain.
+
+### How to Delete Your Organization
+
+1.  Select the Organization you want to delete and click its **"Delete"** button.
+2.  A confirmation modal will appear, requiring you to verify this action.
+3. Click the "Delete" button to permanently remove the Organization. To abort the deletion, click "Cancel".
+
+<img src="/cloud/identity/organizations/org-management/delete_org.png" alt="Delete Organization" style="width: 30%;" />
+
+[^1]: Existing users who click this invitation link might encounter a "Page not found" error. This is a temporary bug and is being addressed.

content/en/cloud/identity/organizations/org-management/delete_org.png

@@ -1,47 +1,71 @@
 ---
 title: User Management
 description: >
-  Efficiently manage and organize users within Layer5 Cloud with our comprehensive user management capabilities.
+  Learn how to create, add, invite, and manage users within Layer5 Cloud.
 weight: 4
 categories: [Identity]
 tags: [users]
 ---
 
-There are three essential aspects of user management:
+This guide outlines methods for creating user accounts, adding users to organizations, inviting new members, and managing user access within Layer5 Cloud to maintain a secure and organized environment.
 
-- Create User
-- Add User/ Remove User
-- Invite User
+![User Management options](/cloud/identity/users/org_invite.png)
 
-## Create User
+## Create User Account
 
 Seamlessly initiate new user accounts, ensuring a smooth onboarding process. Specify user details, such as email, and tailor their access by adding them to one or more organizations. Optionally assign roles, defining their scope within the platform. Complete the process by sending a personalized account setup email, streamlining the user's introduction to Layer5 Cloud.
 
-<img src="/cloud/identity/users/create-user.gif" alt="Create User" />
+![Create User](/cloud/identity/users/create-user.gif)
 
-{{< alert type="info" title="Note" >}}
-Only Provider Admins and Organization Admin can create users. For more information, see [Roles](/cloud/security/roles).
+{{< alert type="info" title="Permission Required for User Creation" >}}
+Only Provider Admins and Organization Admins can create users. For more information, see [Roles](/cloud/security/roles).
 {{< /alert >}}
 
-## Add User/ Remove User
+## Add / Remove Existing User
 
-Add or remove users from the selected organization.
+This section explains how to add existing Layer5 Cloud users to one of your organizations or remove them.
 
-1. Navigate to the **Users** tab in the Identity section.
+![Flow for organization and team membership](/cloud/identity/users/Slide41.svg)
+
+### Adding a User to an Organization
+
+If someone already has a Layer5 Cloud account but isn't part of your organization, you can add them.
+
+1. Go to the Users tab in the Identity section 
 2. Click the **Add User** button.
 3. Select the organization to which you want to add the user.
 4. Select the user from the list of available users.
-5. From below chips, click on cross icon to remove the user from the organization.
+5. Assign appropriate roles within the organization.
 
-<img src="/cloud/identity/users/add-user.gif" alt="Add User" />
+![Add User to Organization](/cloud/identity/users/add-user.gif)
 
-![Flow for organization and team membership](/cloud/identity/users/Slide41.svg)
+### Removing Users from an Organization
+
+You can remove users from an organization one by one or several at once. This action takes away their membership and access to that specific organization's resources but doesn’t delete their overall Layer5 Cloud account.
+
+#### Method 1: Individual User Removal (One by One)
+   * **Locate the User:** Find the specific user you wish to remove from the list.
+   * **Use Row Action:** Click the "Remove User" icon.
+   * **Confirm:** When prompted, confirm your decision to remove the user from the organization.
+
+#### Method 2: Bulk User Removal (Multiple Users at Once)
+   * **Select Users:** Use the checkboxes next to each user's name to select all the users you intend to remove.
+   * **Use Bulk Action:** Click the "Delete" button.
+   * **Confirm:** When prompted, confirm that you want to remove all the selected users from the organization.
+
+![Removing Users from an Organization](/cloud/identity/users/remove_user.png)
 
-## Invite User
+## Invite User via Email
 
-Invite users to join your organization. Specify the user's name and email address and tailor their involvement by adding them to **organizations** and **teams**, optionally assigning predefined roles.
+You can invite new or existing users to join one of your organizations by sending them an email invitation.
 
+* **How to Invite:**
+    1.  Click the "Invite User" button.
+    2.  Enter the person's First Name, Last Name, and Email address.
+    3.  Assign them to a target Organization. Optionally, Team(s) and Organization Role(s) they will receive.
+    4.  Layer5 Cloud sends an invitation email to the user.
+* **What the User Does:** The person you invited will click a link in the email to accept. If they're new to Layer5 Cloud, they'll need to create an account first before they can join your organization.
 
-{{< alert type="info" title="Note" >}}
-An Organization Admin can assign organization roles to users but provider roles can only be assigned by Provider Admins. For more information, see [Roles](/cloud/security/roles).
+{{< alert type="info" title="Permissions for Role Assignment" >}}
+An Organization Admin can assign organization roles to users, but provider roles can only be assigned by Provider Admins. For more information, see [Roles](/cloud/security/roles).
 {{< /alert >}}