New user doc feedback (#42)

MelissaFlinn · web-flow · commit 7f983f13e70d · 2024-09-09T08:39:41.000-04:00
* rhoai-7399 add new user feedback

* rhoai-7399 make format of notes consistent

* another minor update
diff --git a/workshop/docs/modules/ROOT/assets/images/projects/ds-project-my-storage-form.png b/workshop/docs/modules/ROOT/assets/images/projects/ds-project-my-storage-form.png
diff --git a/workshop/docs/modules/ROOT/assets/images/projects/ds-project-pipeline-artifacts-form.png b/workshop/docs/modules/ROOT/assets/images/projects/ds-project-pipeline-artifacts-form.png
diff --git a/workshop/docs/modules/ROOT/assets/images/projects/launch-jupyter-link.png b/workshop/docs/modules/ROOT/assets/images/projects/launch-jupyter-link.png
diff --git a/workshop/docs/modules/ROOT/assets/images/workbenches/create-workbench-form-env-storage.png b/workshop/docs/modules/ROOT/assets/images/workbenches/create-workbench-form-env-storage.png
diff --git a/workshop/docs/modules/ROOT/pages/automating-workflows-with-pipelines.adoc b/workshop/docs/modules/ROOT/pages/automating-workflows-with-pipelines.adoc
@@ -19,7 +19,7 @@ image::pipelines/wb-pipeline-launcher.png[Pipeline buttons]
 +
 image::pipelines/wb-pipeline-editor-button.png[Pipeline Editor button, 100]
 +
-You've created a blank pipeline! 
+You've created a blank pipeline.
 
 . Set the default runtime image for when you run your notebook or Python code.
 
@@ -35,7 +35,7 @@ image::pipelines/wb-pipeline-properties-tab.png[Pipeline Properties Tab]
 +
 image::pipelines/wb-pipeline-runtime-image.png[Pipeline Runtime Image0, 400]
 
-. Save the pipeline.
+. Select *File* -> *Save Python File*.
 
 == Add nodes to your pipeline
 
@@ -55,7 +55,7 @@ image::pipelines/wb-pipeline-connect-nodes.png[Connect Nodes, 400]
 
 Set node properties to specify the training file as a dependency.
 
-Note: If you don't set this file dependency, the file is not included in the node when it runs and the training job fails.
+NOTE: If you don't set this file dependency, the file is not included in the node when it runs and the training job fails.
 
 . Click the `1_experiment_train.ipynb` node.
 +
@@ -103,7 +103,7 @@ The secret is named `aws-connection-my-storage`.
 
 [NOTE] 
 ====
-If you named your data connection something other than `My Storage`, you can obtain the secret name in the {productname-short} dashboard by hovering over the resource information icon *?* in the *Data Connections* tab. 
+If you named your data connection something other than `My Storage`, you can obtain the secret name in the {productname-short} dashboard by hovering over the help (?) icon in the *Data Connections* tab. 
 
 image::pipelines/dsp-dc-secret-name.png[My Storage Secret Name, 400]
 ====
@@ -136,16 +136,17 @@ image::pipelines/wb-pipeline-node-remove-env-var.png[Remove Env Var]
 
 .. Under *Kubernetes Secrets*, click *Add*.
 +
-image::pipelines/wb-pipeline-add-kube-secret.png[Add Kube Secret]
+image::pipelines/wb-pipeline-add-kube-secret.png[Add Kubernetes Secret]
 
 .. Enter the following values and then click *Add*.
-** *Environment Variable*: `AWS_ACCESS_KEY_ID`
++
+* *Environment Variable*: `AWS_ACCESS_KEY_ID`
 ** *Secret Name*: `aws-connection-my-storage`
 ** *Secret Key*: `AWS_ACCESS_KEY_ID`
 +
 image::pipelines/wb-pipeline-kube-secret-form.png[Secret Form, 400]
 
-.. Repeat Steps 2a and 2b for each set of these Kubernetes secrets:
+. Repeat Step 2 for each of the following Kubernetes secrets:
 
 * *Environment Variable*: `AWS_SECRET_ACCESS_KEY`
 ** *Secret Name*: `aws-connection-my-storage`
@@ -163,7 +164,7 @@ image::pipelines/wb-pipeline-kube-secret-form.png[Secret Form, 400]
 ** *Secret Name*: `aws-connection-my-storage`
 ** *Secret Key*: `AWS_S3_BUCKET`
 
-. *Save* and *Rename* the `.pipeline` file.
+. Select *File* -> *Save Python File As* to save and rename the pipeline. For example, rename it to `My Train Save.pipeline`.
 
 == Run the Pipeline 
 
diff --git a/workshop/docs/modules/ROOT/pages/conclusion.adoc b/workshop/docs/modules/ROOT/pages/conclusion.adoc
@@ -5,9 +5,7 @@
 [.text-center.strong]
 == Conclusion
 
-Congratulations!
-
-In this {deliverable}, you learned how to incorporate data science and artificial intelligence (AI) and machine learning (ML) into an OpenShift development workflow.
+Congratulations. In this {deliverable}, you learned how to incorporate data science,  artificial intelligence, and machine learning into an OpenShift development workflow.
 
 You used an example fraud detection model and completed the following tasks:
 
diff --git a/workshop/docs/modules/ROOT/pages/creating-a-workbench.adoc b/workshop/docs/modules/ROOT/pages/creating-a-workbench.adoc
@@ -16,7 +16,7 @@ A workbench is an instance of your development and experimentation environment.
 
 . Click the *Workbenches* tab, and then click the *Create workbench* button.
 +
-image::workbenches/ds-project-create-workbench.png[Create workbench button]
+image::workbenches/ds-project-create-workbench.png[Create workbench button, 300]
 
 . Fill out the name and description.
 +
diff --git a/workshop/docs/modules/ROOT/pages/creating-data-connections-to-storage.adoc b/workshop/docs/modules/ROOT/pages/creating-data-connections-to-storage.adoc
@@ -1,7 +1,9 @@
 [id='creating-data-connections-to-storage']
 = Creating data connections to your own S3-compatible object storage
 
-NOTE: If you do not have your own s3-compatible storage, or if you want to use a disposable local Minio instance instead, skip this section and follow the steps in xref:running-a-script-to-install-storage.adoc[Running a script to install local object storage buckets and create data connections].
+If you have existing S3-compatible storage buckets that you want to use for this {deliverable}, you must create a data connection to one storage bucket for saving your data and models and, if you want to complete the pipelines section of this {deliverable}, create another data connection to a different storage bucket for saving pipeline artifacts.
+
+NOTE: If you do not have your own s3-compatible storage, or if you want to use a disposable local Minio instance instead, skip this section and follow the steps in xref:running-a-script-to-install-storage.adoc[Running a script to install local object storage buckets and create data connections].   The provided script automatically completes the following tasks for you: creates a Minio instance in your project, creates two storage buckets in that Minio instance, creates two data connections in your project, one for each bucket and both using the same credentials, and installs required network policies for service mesh functionality. 
 
 .Prerequisite
 
@@ -15,45 +17,48 @@ To create data connections to your existing S3-compatible storage buckets, you n
 
 If you don't have this information, contact your storage administrator.
 
-.Procedures
-
-Create data connections to your two storage buckets.
+.Procedure
 
-*Create a data connection for saving your data and models*
+. Create a data connection for saving your data and models:
 
-. In the {productname-short} dashboard, navigate to the page for your data science project.
+.. In the {productname-short} dashboard, navigate to the page for your data science project.
 
-. Click the *Data connections* tab, and then click *Add data connection*.
+.. Click the *Data connections* tab, and then click *Add data connection*.
 +
 image::projects/ds-project-add-dc.png[Add data connection]
 
-. Fill out the *Add data connection* form and name your connection *My Storage*. This connection is for saving your personal work, including data and models.
+.. Fill out the *Add data connection* form and name your connection *My Storage*. This connection is for saving your personal work, including data and models. 
++
+NOTE: Skip the *Connected workbench* item. You add data connections to a workbench in a later section.
 +
 image::projects/ds-project-my-storage-form.png[Add my storage form]
 
-. Click *Add data connection*.
-
-*Create a data connection for saving pipeline artifacts*
+.. Click *Add data connection*.
 
+. Create a data connection for saving pipeline artifacts:
++
 NOTE: If you do not intend to complete the pipelines section of the {deliverable}, you can skip this step.
 
-. Click *Add data connection*.
+.. Click *Add data connection*.
 
-. Fill out the form and name your connection *Pipeline Artifacts*.
+.. Fill out the form and name your connection *Pipeline Artifacts*.
++
+NOTE: Skip the *Connected workbench* item. You add data connections to a workbench in a later section.
 +
 image::projects/ds-project-pipeline-artifacts-form.png[Add pipeline artifacts form]
 
-. Click *Add data connection*.
+.. Click *Add data connection*.
 
 
 .Verification
+
 In the *Data connections* tab for the project, check to see that your data connections are listed.
 
 image::projects/ds-project-dc-list.png[List of project data connections]
 
 
 .Next steps
 
-* Configure a pipeline server as described in xref:enabling-data-science-pipelines.adoc[Enabling data science pipelines]
+If you want to complete the pipelines section of this {deliverable}, go to xref:enabling-data-science-pipelines.adoc[Enabling data science pipelines].
 
-* Create a workbench and select a notebook image as described in xref:creating-a-workbench.adoc[Creating a workbench]
+Otherwise, skip to xref:creating-a-workbench.adoc[Creating a workbench].
diff --git a/workshop/docs/modules/ROOT/pages/deploying-a-model-multi-model-server.adoc b/workshop/docs/modules/ROOT/pages/deploying-a-model-multi-model-server.adoc
@@ -3,7 +3,7 @@
 
 {productname-short} multi-model servers can host several models at once. You create a new model server and deploy your model to it.
 
-.Prerequiste
+.Prerequisite
 
 * A user with `admin` privileges has enabled the multi-model serving platform on your OpenShift cluster.
 
@@ -13,7 +13,7 @@
 +
 image::model-serving/ds-project-model-list-add.png[Models]
 +
-*Note:* Depending on how model serving has been configured on your cluster, you might see only one model serving platform option.
+NOTE: Depending on how model serving has been configured on your cluster, you might see only one model serving platform option.
 
 . In the *Multi-model serving platform* tile, click *Add model server*.
 
@@ -43,7 +43,7 @@ image::model-serving/deploy-model-form-mm.png[Deploy model from for multi-model
 
 .Verification
 
-Wait for the model to deploy and for the *Status* to show a green checkmark.
+Notice the loading symbol under the *Status* section. It will change to a green checkmark when the deployment is completes successfully. 
 
 image::model-serving/ds-project-model-list-status-mm.png[Deployed model status]
 
diff --git a/workshop/docs/modules/ROOT/pages/deploying-a-model-single-model-server.adoc b/workshop/docs/modules/ROOT/pages/deploying-a-model-single-model-server.adoc
@@ -3,10 +3,10 @@
 
 {productname-short} single-model servers host only one model. You create a new model server and deploy your model to it.
 
-*Note:* Depending on how model serving has been configured on your cluster, you might see only one model serving platform option.
+NOTE: Depending on how model serving has been configured on your cluster, you might see only one model serving platform option.
 
 
-.Prerequiste
+.Prerequisite
 
 * A user with `admin` privileges has enabled the single-model serving platform on your OpenShift cluster.
 
@@ -16,7 +16,7 @@
 +
 image::model-serving/ds-project-model-list-add.png[Models]
 +
-*Note:* Depending on how model serving has been configured on your cluster, you might see only one model serving platform option.
+NOTE: Depending on how model serving has been configured on your cluster, you might see only one model serving platform option.
 
 . In the *Single-model serving platform* tile, click *Deploy model*.
 . In the form, provide the following values:
@@ -33,7 +33,7 @@ image::model-serving/deploy-model-form-sm.png[Deploy model from for single-model
 
 .Verification
 
-Wait for the model to deploy and for the *Status* to show a green checkmark.
+Notice the loading symbol under the *Status* section. It will change to a green checkmark when the deployment is completes successfully.
 
 image::model-serving/ds-project-model-list-status-sm.png[Deployed model status]
 
diff --git a/workshop/docs/modules/ROOT/pages/deploying-a-model.adoc b/workshop/docs/modules/ROOT/pages/deploying-a-model.adoc
@@ -8,7 +8,7 @@ Now that the model is accessible in storage and saved in the portable ONNX forma
 * *Single-model serving* - Each model in the project is deployed on its own model server. This platform works well for large models or models that need dedicated resources.
 * *Multi-model serving* - All models in the project are deployed on the same model server. This platform is suitable for sharing resources amongst deployed models.  Multi-model serving is the only option offered in the {org-name} Developer Sandbox environment.
 
-*Note:* For each project, you can specify only one model serving platform. If you want to change to the other model serving platform, you must create a new project.
+NOTE: For each project, you can specify only one model serving platform. If you want to change to the other model serving platform, you must create a new project.
 
 For this {deliverable}, since you are only deploying only one model, you can select either serving type. The steps for deploying the fraud detection model depend on the type of model serving platform you select:
 
diff --git a/workshop/docs/modules/ROOT/pages/enabling-data-science-pipelines.adoc b/workshop/docs/modules/ROOT/pages/enabling-data-science-pipelines.adoc
@@ -29,7 +29,7 @@ image::projects/ds-project-create-pipeline-server-form.png[Selecting the Pipelin
 
 . Click *Configure pipeline server*.
 
-. Wait until the spinner disappears and *No pipelines yet* is displayed.
+. Wait until the spinner disappears and *Start by importing a pipeline* is displayed.
 +
 [IMPORTANT]
 ====
diff --git a/workshop/docs/modules/ROOT/pages/index.adoc b/workshop/docs/modules/ROOT/pages/index.adoc
@@ -6,17 +6,15 @@
 [.text-center.strong]
 == Introduction
 
-Welcome!
-
-In this {deliverable}, you learn how to incorporate data science and artificial intelligence and machine learning (AI/ML) into an OpenShift development workflow.
+Welcome. In this {deliverable}, you learn how to incorporate data science and artificial intelligence and machine learning (AI/ML) into an OpenShift development workflow.
 
 You will use an example fraud detection model to complete the following tasks:
 
 * Explore a pre-trained fraud detection model by using a Jupyter notebook.
 * Deploy the model by using {productname-short} model serving.
 * Refine and train the model by using automated pipelines.
 
-And you do not have to install anything on your own computer, thanks to https://www.redhat.com/en/technologies/cloud-computing/openshift/openshift-data-science[{productname-long}].
+And you do not have to install anything on your own computer, thanks to https://www.redhat.com/en/technologies/cloud-computing/openshift/openshift-ai[{productname-long}].
 
 == About the example fraud detection model
 
@@ -30,11 +28,13 @@ Based on this data, the model outputs the likelihood of the transaction being fr
 
 == Before you begin
 
-If you don't already have an instance of {productname-long}, see the https://developers.redhat.com/products/red-hat-openshift-ai/download[{productname-long} page on the {org-name} Developer website]. There, you can create an account and access the *free {org-name} Developer Sandbox* or you can learn how to install {productname-short} on *your own OpenShift cluster*.
+You should have access to an OpenShift cluster where {productname-long} is installed. 
+
+If don't have access to a cluster that includes an instance of {productname-short}, see the https://developers.redhat.com/products/red-hat-openshift-ai/download[{productname-long} page on the {org-name} Developer website]. There, you can create an account and access the https://console.redhat.com/openshift/sandbox[*free {org-name} Developer Sandbox*] or you can learn how to install {productname-short} on *your own OpenShift cluster*.
 
 [IMPORTANT]
 ====
 If your cluster uses self-signed certificates, before you begin the {deliverable}, your {productname-short} administrator must add self-signed certificates for {productname-short} as described in link:https://docs.redhat.com/en/documentation/red_hat_openshift_ai_self-managed/2-latest/html/installing_and_uninstalling_openshift_ai_self-managed/working-with-certificates_certs[Working with certificates].
 ====
 
-If you're ready, xref:navigating-to-the-dashboard.adoc[start the {deliverable}!]
+If you're ready, xref:navigating-to-the-dashboard.adoc[start the {deliverable}].
diff --git a/workshop/docs/modules/ROOT/pages/navigating-to-the-dashboard.adoc b/workshop/docs/modules/ROOT/pages/navigating-to-the-dashboard.adoc
@@ -23,7 +23,7 @@ image::projects/login-with-openshift.png[OpenShift login, 300]
 
 The {productname-short} dashboard shows the *Home* page.
 
-*Note:* You can navigate back to the OpenShift console by clicking the application launcher to access the OpenShift console.
+NOTE: You can navigate back to the OpenShift console by clicking the application launcher to access the OpenShift console.
 
 image::projects/ds-console-ocp-tile.png[OCP console link]
 
diff --git a/workshop/docs/modules/ROOT/pages/preparing-a-model-for-deployment.adoc b/workshop/docs/modules/ROOT/pages/preparing-a-model-for-deployment.adoc
@@ -3,7 +3,11 @@
 
 After you train a model, you can deploy it by using the {productname-short} model serving capabilities.
 
-To prepare a model for deployment, you must move the model from your workbench to your S3-compatible object storage. You use the data connection that you created in the xref:storing-data-with-data-connections.adoc[Storing data with data connections] section and upload the model from a notebook. You also convert the model to the portable ONNX format. ONNX allows you to transfer models between frameworks with minimal preparation and without the need for rewriting the models.
+To prepare a model for deployment, you must complete the following tasks:
+
+* Move the model from your workbench to your S3-compatible object storage. You use the data connection that you created in the xref:storing-data-with-data-connections.adoc[Storing data with data connections] section and upload the model from a notebook. 
+
+* Convert the model to the portable ONNX format. ONNX allows you to transfer models between frameworks with minimal preparation and without the need for rewriting the models.
 
 .Prerequisites
 
diff --git a/workshop/docs/modules/ROOT/pages/running-a-pipeline-generated-from-python-code.adoc b/workshop/docs/modules/ROOT/pages/running-a-pipeline-generated-from-python-code.adoc
@@ -1,7 +1,7 @@
 [id='running-a-pipeline-generated-from-python-code']
 = Running a data science pipeline generated from Python code
 
-In the previous section, you created a simple pipeline by using the GUI pipeline editor. It's often desirable to create pipelines by using code that can be version-controlled and shared with others. The https://github.com/kubeflow/pipelines[kfp] SDK provides a Python API for creating pipelines. The SDK is available as a Python package that you can install by using the `pip install kfp` command. With this package, you can use Python code to create a pipeline and then compile it to YAML format. Then you can import the YAML code into {productname-short}.
+In the previous section, you created a simple pipeline by using the GUI pipeline editor. It's often desirable to create pipelines by using code that can be version-controlled and shared with others. The https://github.com/kubeflow/pipelines[Kubeflow pipelines (kfp)] SDK provides a Python API for creating pipelines. The SDK is available as a Python package that you can install by using the `pip install kfp` command. With this package, you can use Python code to create a pipeline and then compile it to YAML format. Then you can import the YAML code into {productname-short}.
 
 This {deliverable} does not delve into the details of how to use the SDK. Instead, it provides the files for you to view and upload.
 
diff --git a/workshop/docs/modules/ROOT/pages/running-a-script-to-install-storage.adoc b/workshop/docs/modules/ROOT/pages/running-a-script-to-install-storage.adoc
@@ -53,7 +53,7 @@ image::projects/ocp-console-project-selected.png[Selected project]
 
 . Copy the following code and paste it into the *Import YAML* editor.
 +
-*Note:* This code gets and applies the `setup-s3-no-sa.yaml` file.
+NOTE: This code gets and applies the `setup-s3-no-sa.yaml` file.
 +
 [.lines_space]
 [.console-input]
@@ -113,6 +113,6 @@ You should see a "Resources successfully created" message and the following reso
 
 .Next steps
 
-* Configure a pipeline server as described in xref:enabling-data-science-pipelines.adoc[Enabling data science pipelines]
+If you want to complete the pipelines section of this {deliverable}, go to xref:enabling-data-science-pipelines.adoc[Enabling data science pipelines].
 
-* Create a workbench and select a notebook image as described in xref:creating-a-workbench.adoc[Creating a workbench]
+Otherwise, skip to xref:creating-a-workbench.adoc[Creating a workbench].
diff --git a/workshop/docs/modules/ROOT/pages/running-code-in-a-notebook.adoc b/workshop/docs/modules/ROOT/pages/running-code-in-a-notebook.adoc
@@ -33,7 +33,7 @@ Notebooks are so named because they are like a physical _notebook_: you can take
 
 == Try it
 
-Now that you know the basics, give it a try!
+Now that you know the basics, give it a try.
 
 .Prerequisite
 
diff --git a/workshop/docs/modules/ROOT/pages/setting-up-your-data-science-project.adoc b/workshop/docs/modules/ROOT/pages/setting-up-your-data-science-project.adoc
@@ -11,9 +11,9 @@ image::projects/launch-jupyter-link.png[Launch Jupyter link]
 +
 Note that it is possible to start a Jupyter notebook by clicking the *Launch Jupyter* link. However, it would be a one-off Jupyter notebook run in isolation. To implement a data science workflow, you must create a data science project (as described in the following procedure). Projects allow you and your team to organize and collaborate on resources within separated namespaces. From a project you can create multiple workbenches, each with their own IDE environment (for example, JupyterLab), and each with their own data connections and cluster storage. In addition, the workbenches can share models and data with pipelines and model servers.
 
-. If you are using the {org-name} Developer Sandbox, you are provided with a default data science project (for example, `myname-dev`). Select it and skip over the next step to the *Verification* section.
+. If you are using your own OpenShift cluster, click *Create data science project*. 
 +
-If you are using your own OpenShift cluster, click *Create data science project*.
+NOTE: If you are using the {org-name} Developer Sandbox, you are provided with a default data science project (for example, `myname-dev`). Select it and skip over the next step to the *Verification* section.
 
 . Enter a display name and description. Based on the display name, a resource name is automatically generated, but you can change if you prefer.
 +
diff --git a/workshop/docs/modules/ROOT/pages/storing-data-with-data-connections.adoc b/workshop/docs/modules/ROOT/pages/storing-data-with-data-connections.adoc
diff --git a/workshop/docs/modules/ROOT/pages/testing-the-model-api.adoc b/workshop/docs/modules/ROOT/pages/testing-the-model-api.adoc
diff --git a/workshop/docs/modules/ROOT/pages/training-a-model.adoc b/workshop/docs/modules/ROOT/pages/training-a-model.adoc

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ A workbench is an instance of your development and experimentation environment.`
`16`	`16`
`17`	`17`	`. Click the Workbenches tab, and then click the Create workbench button.`
`18`	`18`	`+`
`19`		`-image::workbenches/ds-project-create-workbench.png[Create workbench button]`
	`19`	`+image::workbenches/ds-project-create-workbench.png[Create workbench button, 300]`
`20`	`20`
`21`	`21`	`. Fill out the name and description.`
`22`	`22`	`+`