Add high level workspace documentation (#5282) (#7906)

(cherry picked from commit f62795c)

Signed-off-by: Yulong Ruan <[email protected]>
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

src/plugins/workspace/README.md

@@ -1,4 +1,114 @@
 # Workspace
+The workspace feature allows users to customize their OpenSearch-Dashboards experience with curated use cases, for example, user can create a workspace particularly for observability use case so that they can concentrate on observability related functionaties. Also, workspace helps users organize visual assets, such as dashboards and visualizations, such assets are isolated by workspace. This makes it a valuable tool for OpenSearch-Dashboards users who want a more precise and flexible workflow.
+
+## Scopes
+The workspace only cares about data stored via saved objects(OSD metadata). The management of data stored by plugins that maintain their independent data stores within their own OpenSearch indexes is OUT OF THE SCOPE.
+
+## Workspace data model
+The Workspace data model defines the fundamental structure for managing isolated environments dedicated to metadata management within OpenSearch Dashboards.
+
+```typescript
+interface Workspace {
+  id: string
+  name: string
+  description?: string
+  features?: string[]
+}
+```
+
+1. `id`: A unique identifier that distinguishes each workspace.
+2. `name`: The name of the workspace.
+3. `description`: A description providing context for the workspace.
+4. `features`: An array of application IDs associated with the workspace, derived from the plugins registered. These application IDs
+    are used to filter and display the relevant plugins in the left navigation menu when accessing the workspace. It serves as a visual
+    mechanism for organizing and presenting features.
+
+
+**Workspace object example**
+```typescript
+{
+  id: "M5NqCu",
+  name: "Observability team",
+  description: "Observability team workspace",
+  features: ["use-case-observability"],
+}
+```
+
+The above object defines a workspace with name `Observability team` that's create with `observability` features by specifying an use case `use-case-observability`. An use case maps to multiple predefined OSD features, only the defined features will be available within the workspace. Use case strings are predefined, there are five types of use cases, except `use-case-all` which all features are available, the other four types of use cases have curated features defined:
+1. `use-case-observability`
+2. `use-case-security-analytics`
+3. `use-case-search`
+4. `use-case-analytics`
+5. `use-case-all`
+
+## Associate saved objects with workspaces
+Saved objects, such as dashboards, visualizations, and index patterns, form the backbone of data visualization and analysis in OpenSearch Dashboards.
+However, as the volume of saved objects grows, keeping them organized becomes increasingly challenging. Grouping saved objects into distinct workspaces,
+each serving a specific purpose or team. This association not only simplifies the process of finding and accessing relevant saved objects but also
+enhances security and access control (Please ref to this [DOC](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4633) for more details
+about access control).
+
+A new attribute, `workspaces`, is being added to saved objects which type is an array of string. A saved object can be associated with one or multiple workspaces. The saved objects(dashboards, visualizations, etc) will only be showed up in the associated workspaces.
+
+The follow example shows the dashboard object is associated with workspace which id is `M5NqCu`
+```typescript
+{
+  type: "dashboard",
+  id: "da123f20-6680-11ee-93fa-df944ec23359",
+  workspaces: ["M5NqCu"]
+}
+```
+
+Saved object can also be associated with multiple workspaces, this is useful in scenarios where a saved object is relevant to multiple teams, projects, or use cases.
+
+Consider the following example, where a data source is associated with multiple workspaces:
+```typescript
+{
+  type: "data-source",
+  id: "da123f20-6680-11ee-93fa-df944ec23359",
+  workspaces: ["M5NqCu", "<TeamA-workspace-id>", "<Analytics-workspace-id>"]
+}
+```
+By allowing saved objects to be linked with multiple workspaces, this enables users to share and collaborate on resources across various workspaces(teams).
+
+## Non-workspace saved objects
+While the introduction of workspaces in OSD provides a powerful framework for organizing and managing saved objects, it's important to note that not all saved objects are necessarily associated with workspaces. Some saved objects, by nature or purpose, may exist independently of workspaces.
+
+For example, the global UI settings object. This object contains configurations and settings that apply globally across OSD, affecting the overall user interface and user experience. These settings are not tied to any specific workspace because they are intended to impact the entire OSD. Such objects won't have `workspaces` attribute.
+
+The coexistence of workspace-associated saved objects and those without workspace association ensures that OSD strikes a balance between context-specific customization and system-wide consistency.
+
+## Duplicate saved objects among workspaces
+When duplicating objects, it creates hard copies of the objects in the target workspace, regardless of their original workspaces.
+
+For example, if duplicate the following object to `<target-workspace>`
+```typescript
+{
+  type: "visualization",
+  id: "da123f20-6680-11ee-93fa-df944ec23359",
+  workspaces: ["M5NqCu", "<TeamA-workspace-id>", "<Analytics-workspace-id>"]
+}
+```
+
+Then a new object will be created with new `id` and associated with `<target-workspace>`
+```typescript
+{
+  type: "visualization",
+  id: "<new-object-id>",
+  workspaces: ["<target-workspace>"]
+}
+```
+
+### Handling Dependencies
+A significant aspect of duplicating saved objects is the handling of dependencies. Many saved objects, particularly visual objects like dashboards and visualizations, often have a hierarchical structure with dependencies. For example, a dashboard may depend on multiple visualizations, and each visualization may rely on specific index pattern objects.
+
+The duplicating process is not limited to the saved object itself. The user has the flexibility to choose whether or not to duplicate the entire dependency tree. If duplicating the entire dependency hierarchy, all dependencies will be duplicated. For example:
+1. If the visualization depends on specific index pattern objects, these index pattern objects will also be duplicated in `<target-workspace>`.
+2. If the dashboard depends on multiple visualizations, those visualizations and their associated index patterns will be copied as well.
+
+This ensures that the copied saved object in <target-workspace> retains its functionality and context, with all necessary dependencies in place.
+
+Please note that when multiple data source is enabled, duplicating saved objects to another workspace will not take the data source into consideration. Data source is a special type of object that cannot be duplicated but can only be manually assigned to a workspace.
 
 ## Server APIs
 
@@ -317,3 +427,7 @@ POST api/workspaces/_duplicate_saved_objects
 }
 ```
 
+## Appendix
+1. The PR the introduce [object access control](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/5083)
+2. The [PR](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4633/files) of the design doc for saved object access control
+3. Future Vision for Dashboards: [Issue](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/4298)