Add/update documentation on the dashboard flows

.github/ISSUE_TEMPLATE/internal_ux.yml

@@ -15,7 +15,10 @@ body:
     id: goals
     attributes:
       label: Goals
-      description: An itemized list of goals to complete for this ticket
+      description: |
+        An itemized list of goals to complete for this ticket.
+
+        If you don't have specific goals, this could also include the user story or jobs to be done.
       placeholder: |
         * Research...
         * Design...

CONTRIBUTING.md

@@ -1,10 +1,12 @@
+[dev setup documentation]: docs/dev-setup.md#requirements
+
 # Contributing
 
 Contributing encompasses repository specific requirements.
 
 ## Requirements
 
-You can check the requirements of ODH in the [README section](./README.md#requirements).
+To review the ODH requirements, please refer to the [dev setup documentation].
 
 ## Writing code
 

README.md

@@ -1,107 +1,17 @@
-# Open Data Hub Dashboard
-
-A dashboard for Open Data Hub components.
-
-- Shows what's installed
-- Show's what's available for installation
-- Links to component UIs
-- Links to component documentation
-
-## Requirements
-
-ODH requires the following to run:
-
-- [NodeJS and NPM](https://nodejs.org/)
-  - Node recommended version -> `18.16.0`
-  - NPM recommended version -> `9.6.7`
-- [OpenShift CLI](https://docs.openshift.com/container-platform/4.12/cli_reference/openshift_cli/getting-started-cli.html)
-- [kustomize](https://github.com/kubernetes-sigs/kustomize)
-- [podman](https://github.com/containers/podman)
-- Have access to [Quay.io](https://quay.io/)
-
-### Additional tooling requirements
-
-- [OpenShift CLI, the "oc" command](https://docs.openshift.com/container-platform/4.12/cli_reference/openshift_cli/getting-started-cli.html)
-- [Podman](https://github.com/containers/podman)
-- [Quay.io](https://quay.io/)
-
-## Development
-
-   1. Clone the repository
-
-      ``` bash
-      git clone https://github.com/opendatahub-io/odh-dashboard
-      ```
-
-   2. Within the repo context, install project dependencies
-
-      ```bash
-      cd odh-dashboard && npm install
-      ```
-
-### Build project
-
-  ```bash
-  npm run build
-  ```
-
-### Serve development content
-
-This is the default context for running a local UI.  Make sure you build the project using the instructions above prior to running the command below.
-
-  ```bash
-  npm run start
-  ```
+[Dev setup & Requirements]: docs/dev-setup.md
+[Dashboard documentation]: docs/README.md
 
-For in-depth local run guidance review the [contribution guidelines](./CONTRIBUTING.md#Serving%20Content).
-
-### Testing
-
-Run the tests.
-
-  ```bash
-  npm run test
-  ```
-
-Run storybook a11y tests and interaction tests.
-
-  ```bash
-  npm run storybook
-  npm run test:storybook
-  ```
-
-For in-depth testing guidance review the [contribution guidelines](./CONTRIBUTING.md#Testing)
-
-## Deploying the ODH Dashbard
-
-### Official Image Builds
-
-odh-dashboard images are automatically built and pushed to [quay.io](https://quay.io/repository/opendatahub/odh-dashboard) after every commit to the `main` branch. The image tag name format for each image is `main-<COMMIT SHORT HASH>`.
-
-Example: The `main` branch is updated with commit `f76e3952834f453b1d085e8627f9c17297c2f64c`.  The CI system will automatically build an odh-dashboard image based on that code and push the new image to `odh-dashboard:main-f76e395` and updated `odh-dashboard:main` to point to the same image hash.
-
-The [nightly](https://quay.io/opendatahub/odh-dashboard:nightly) tag is a floating tag that is updated nightly and points to the most recent `main-<HASH>` commit from the previous day.
-
-### Deploy using kustomize
-
-The [manifests](./manifests) folder contains a [kustomize](https://kustomize.io) manifest that can be used with `kustomize build`.
-
-### Deploy using a kfdef
+# Open Data Hub Dashboard
 
-The [manifests/kfdef](./manifests/kfdef) folder contains an example kfdef to deploy ODH Dashboard with the Notebook Controller backend is located in [odh-dashboard-kfnbc-test.yaml](manifests/kfdef/odh-dashboard-kfnbc-test.yaml).
+A dashboard for Open Data Hub components, featuring user flows to navigate and interact with the various component parts of the stack.
 
 ## Contributing
 
 Contributing encompasses [repository specific requirements](./CONTRIBUTING.md).
 
-### Triaging
-
-For information on how we triage tickets, see our [triage.md](./docs/triaging.md).
-
 ## Documentation
 
-You can find more information about this project in the [document section](./docs/README.md).
-
-## Releases
+Read more about the Dashboard in one of our documentation links.
 
-For more information on how, when, and what we do for releases, see our [releases.md](./docs/releases.md).
+* [Dev setup & Requirements]
+* [Dashboard documentation]

docs/README.md

@@ -1,11 +1,38 @@
+[Dev setup & Requirements]: dev-setup.md
+[Dashboard Configuration]: dashboard-config.md
+[Settings Panel]: admin-dashboard.md
+[User Interaction]: user-interaction.md
+[Bring Your Own Notebook]: byon.md
+[process flows docs]: process-definition/README.md
+[Architecture]: architecture.md
+[SDK]: SDK.md
+[Old custom APIs]: apis.md
+[releases]: release-steps.md
+
 # Dashboard Documentation
 
-This project is divided into several sections, each one describing features of the dashboard.
+This is the general documentation of the Dashboard component.
+
+## Configuration & Features
+
+> Note: We are working to detail out our feature flows to help with internal documentation efforts.
+
+* [Dashboard Configuration]
+* [Settings Panel]
+* [User Interaction]
+* [Bring Your Own Notebook]
+
+## Developer Readmes
+
+* [Dev setup & Requirements]
+* [Architecture]
+* [SDK]
+  * [Old custom APIs] - Deprecated, moving to SDK
+
+## Process Flows
+
+Read more on how we do things in our [process flows docs].
+
+### Releases
 
-* [ODH Dashboard Architecture](architecture.md)
-* [Dashboard Configuration](dashboard_config.md)
-* [Settings Panel](admin_dashboard.md)
-* [User Interaction](user_interaction.md)
-* [Bring Your Own Notebook](byon.md)
-* [SDK](SDK.md)
-  * [Custom APIs](apis.md) -- Deprecated, moving to SDK
+For more information on how, when, and what we do for releases, see our [releases] documentation.

docs/SDK.md

@@ -1,12 +1,20 @@
+[k8s pass through API]: ../backend/src/routes/api/k8s/pass-through.ts
+[CONTRIBUTING]: ../CONTRIBUTING.md
+[@openshift/dynamic-plugin-sdk]: https://www.npmjs.com/package/@openshift/dynamic-plugin-sdk
+[@openshift/dynamic-plugin-sdk-utils]: https://www.npmjs.com/package/@openshift/dynamic-plugin-sdk-utils
+[@openshift/dynamic-plugin-sdk-webpack]: https://www.npmjs.com/package/@openshift/dynamic-plugin-sdk-webpack
+[jsonpatch]: https://jsonpatch.com/
+[jsonpatch operations]: https://jsonpatch.com/#operations
+
 # OpenShift Plugin SDK
 
-[@openshift/dynamic-plugin-sdk](https://www.npmjs.com/package/@openshift/dynamic-plugin-sdk) is an SDK package for making k8s related calls.
+[@openshift/dynamic-plugin-sdk] is an SDK package for making k8s related calls.
 
 It is technically split into three parts:
 
-- [@openshift/dynamic-plugin-sdk](https://www.npmjs.com/package/@openshift/dynamic-plugin-sdk) -- Core set of tools to build a plugin, we don't use this a lot today, but this is needed to bootstrap our frontend for later inclusion on other systems
-- [@openshift/dynamic-plugin-sdk-utils](https://www.npmjs.com/package/@openshift/dynamic-plugin-sdk-utils) -- This will be where we will pull the most of our content from, it has all the k8s utilities we should need
-- [@openshift/dynamic-plugin-sdk-webpack](https://www.npmjs.com/package/@openshift/dynamic-plugin-sdk-webpack) -- Simply just as it states, a webpack set of tools to help configure out webpack to package up to be an SDK
+- [@openshift/dynamic-plugin-sdk] - Core set of tools to build a plugin, we don't use this a lot today, but this is needed to bootstrap our frontend for later inclusion on other systems
+- [@openshift/dynamic-plugin-sdk-utils] - This is where we will pull most of our content from, it has all the k8s utilities we should need
+- [@openshift/dynamic-plugin-sdk-webpack] - Simply just as it states, a webpack set of tools to help configure out webpack to package up to be an SDK
 
 As of today (2022-08-31), we are not looking to be a plugin. We just want to start moving that direction and making use of the utilities so we don't need custom backend to make API calls.
 
@@ -22,34 +30,34 @@ Instead of using our custom NodeJS backend, we'll want to migrate to using one o
 
 All these are heavily typed and are Generics`*`, so you should be able to infer from the types what is needed. But to help that along, here are a couple helpful notes:
 
-- `model` -- Models are simply just a collection of properties that describes a K8s Resource Type. K8s ones like `ConfigMap` & `Pod` to CRDs like `Notebook` and `OdhDashboardConfig` -- we will create our list of these under `frontend/src/models` -- check it out for examples.
-- `queryOptions` -- These are just simply additional options to help target your call at something; typically you'll be setting `name` and `ns` (aka `namespace`)
+- `model` - Models are simply just a collection of properties that describes a K8s Resource Type. K8s ones like `ConfigMap` & `Pod` to CRDs like `Notebook` and `OdhDashboardConfig` - we will create our list of these under `frontend/src/models` - check it out for examples.
+- `queryOptions` - These are just simply additional options to help target your call at something; typically you'll be setting `name` and `ns` (aka `namespace`)
 
 `*` A couple notes about the Generic nature of these functions
 
-1. You can type the response as well as your input -- aim to do this always for better typing, best have TS doing as much as possible
+1. You can type the response as well as your input - aim to do this always for better typing, best have TS doing as much as possible
 2. Our old types may not be 1:1 compatible with other resource types we have. Likely all you will need to do is convert over to the `K8sResourceCommon` type from the SDK instead of using ours
 
 ### Pass Through API
 
-We have set up a pass through API that will effectively take the path built by the SDK's utilities during one of the k8s{CRUD}Resource calls noted above. This API will use the token of your user provided by our OAuth container and send your request off to a kube instance. We will give up on custom error handling and let the client deal with the error from k8s. 
+We have set up a pass through API that will effectively take the path built by the SDK's utilities during one of the k8s{CRUD}Resource calls noted above. This API will use the token of your user provided by our OAuth container and send your request off to a kube instance. We will give up on custom error handling and let the client deal with the error from k8s.
 
-See the [k8s pass through API](../backend/src/routes/api/k8s/pass-through.ts) here.
+See the [k8s pass through API] here.
 
 ### Pass Through Impersonate User Dev Mode
 
 In order to check regular user permissions without disabling the rest of the backend functionality in `dev mode`, you can add the `DEV_IMPERSONATE_USER` and `DEV_IMPERSONATE_PASSWORD` environment variables to your local setup with valid k8s username and password in your cluster. This will bypass the regular pass-through flow and will add that specific headers to the calls. The steps to impersonate another user are listed as follows:
 
-1. Create a new env variable in your `.env.local` file with this format `DEV_IMPERSONATE_USER=<username>` and `DEV_IMPERSONATE_PASSWORD=<password>` 
-2. Run the dev server for ODH dashboard. If you don't know how to run a local dev server, please refer to [CONTRIBUTING](../CONTRIBUTING.md) 
+1. Create a new env variable in your `.env.local` file with this format `DEV_IMPERSONATE_USER=<username>` and `DEV_IMPERSONATE_PASSWORD=<password>`
+2. Run the dev server for ODH dashboard. If you don't know how to run a local dev server, please refer to [CONTRIBUTING]
 3. Click on the username on the top right corner to open the dropdown menu, and choose `Start impersonate`, then the page will refresh and you will be impersonating as the user you set up in step 1
 4. To stop impersonating, click on the `Stop impersonate` button in the header toolbar
 
 NOTE: You may not be able to read data from some Prometheus applications when impersonating another user. In the DEV_MODE, we use the external route to fetch Prometheus data, and the route might connect to a target port that's not accessible by a regular user even if the bearer token is set. To validate that, you may need to deploy the image to the cluster.
 
 ## Patches
 
-Patches are based on [jsonpatch](https://jsonpatch.com/). For those who are unaware of the details let's do a quick breakdown on how they work. When making a `k8sPatchResource` call, it will ask for `Patches[]`. A `Patch` is just simply a straight forward operation on the existing resource.
+Patches are based on [jsonpatch]. For those who are unaware of the details let's do a quick breakdown on how they work. When making a `k8sPatchResource` call, it will ask for `Patches[]`. A `Patch` is just simply a straight forward operation on the existing resource.
 
 Say you wanted to update a `ConfigMap` to have a new property:
 
@@ -64,10 +72,10 @@ k8sPatchResource({
 ```
 
 - `op` is what kind of operation to apply to this path
-  - 'add' -- adds a new item
-  - 'replace' -- updates an existing item
-  - 'remove' -- removes the item (you'd omit `value` naturally as there is no value for removing)
-  - There are other operations you can do as well ([see the docs](https://jsonpatch.com/#operations))
+  - 'add' - adds a new item
+  - 'replace' - updates an existing item
+  - 'remove' - removes the item (you'd omit `value` naturally as there is no value for removing)
+  - There are other operations you can do as well (see the [jsonpatch operations])
 - `path` is the path from the root of the k8s object using `/` as a deliminator, include the key you want to modify
   - Unless it is a complex object you're adding, you'll likely specify `value` as a string/number
 

docs/apis.md

@@ -1,5 +1,11 @@
+<!-- TODO: Deprecated; should point at route folders and not document them -->
+[architectural documentation]: architecture.md#custom-backend-business-logic
+
 # Backend APIs
-The backend for the dashboard is node REST server that performs k8s calls on behalf of the frontend. The following are a list of current apis and there functionality.
+
+> Note: These flows are deprecated in the [architectural documentation]
+
+The backend for the dashboard is node REST server that performs k8s calls on behalf of the frontend. The following are a list of current apis and their functionality.
 
 ## Endpoints and methods
 
@@ -39,11 +45,11 @@ The backend for the dashboard is node REST server that performs k8s calls on beh
 
 ### /notebook/{notebook}
 
-**GET** - Retrieves a specific notebook by it's id.  This returns a single [notebook object](https://github.com/opendatahub-io/odh-dashboard/blob/bf49dc23cd4b5477111ad4590e401a423186fa54/backend/src/types.ts#L259)
+**GET** - Retrieves a specific notebook by its id.  This returns a single [notebook object](https://github.com/opendatahub-io/odh-dashboard/blob/bf49dc23cd4b5477111ad4590e401a423186fa54/backend/src/types.ts#L259)
 
-**DELETE** - Deletes a specific notebook image using it's notebook id.  
+**DELETE** - Deletes a specific notebook image using its notebook id.
 
-**PUT** - Updates a specific notebook by it's id.  The payload should be the updated fields as shown in a [notebook object](https://github.com/opendatahub-io/odh-dashboard/blob/bf49dc23cd4b5477111ad4590e401a423186fa54/backend/src/types.ts#L259)
+**PUT** - Updates a specific notebook by its id.  The payload should be the updated fields as shown in a [notebook object](https://github.com/opendatahub-io/odh-dashboard/blob/bf49dc23cd4b5477111ad4590e401a423186fa54/backend/src/types.ts#L259)
 
 ### /quickstarts
 
@@ -63,4 +69,4 @@ The backend for the dashboard is node REST server that performs k8s calls on beh
 
 ### /validate-isv/results
 
-**GET** - Retrieves the current status of an ISV. 
+**GET** - Retrieves the current status of an ISV.