doc-update-quality-assessment (#112)

* doc-update-quality-assessment

* prep-for-dita-conversion

* two minor adjustments

* doc-update incorporate peer review feedback

* Update workshop/docs/modules/ROOT/nav.adoc

Co-authored-by: RHRolun <[email protected]>

---------

Co-authored-by: RHRolun <[email protected]>

Author: MelissaFlinn

workshop/docs/modules/ROOT/nav.adoc

@@ -23,9 +23,15 @@
 * 4. Data Science Pipelines
 // ** xref:enabling-data-science-pipelines.adoc[1. Enable Pipelines]
 ** xref:automating-workflows-with-pipelines.adoc[1. Workbench Pipeline Editor]
+*** xref:creating-a-pipeline.adoc[1. Creating a pipeline]
+*** xref:adding-nodes-to-your-pipeline.adoc[2. Adding nodes to your pipeline]
+*** xref:specifying-the-training-file-as-a-dependency.adoc[3. Specify the training file as a dependency]
+*** xref:creating-and-storing-the-onnx-output-file.adoc[4. Creating and storing the ONNX-formatted output file]
+*** xref:configuring-the-connection-to-storage.adoc[5. Configuring the connection to storage]
+*** xref:running-your-pipeline.adoc[6. Running your pipeline]
 ** xref:running-a-pipeline-generated-from-python-code.adoc[2. Python Pipelines]
 
-
-* 5. Distributed Training
-** xref:distributed-jobs-with-ray.adoc[1. Distributed Jobs with Ray]
-** xref:distributed-jobs-with-kfto.adoc[2. Distributed Jobs with the Training Operator]
+* 5. Distributing Training
+** xref:distributing-training-jobs.adoc[1.Distributing Training Jobs]
+*** xref:distributing-training-jobs-with-ray.adoc[1. Distributing Training Jobs with Ray]
+*** xref:distributing-training-jobs-with-kfto.adoc[2. Distributing Training Jobs with the Training Operator]

workshop/docs/modules/ROOT/pages/adding-nodes-to-your-pipeline.adoc

@@ -0,0 +1,31 @@
+:_module-type: PROCEDURE
+
+[id='adding-nodes-to-your-pipeline']
+= Adding nodes to your pipeline
+
+[role="_abstract"]
+Add some steps, or *nodes*, in your pipeline for the  `1_experiment_train.ipynb` and `2_save_model.ipynb` notebooks.
+
+.Prerequisites
+
+* You created a pipeline file as described in xref:creating-a-pipeline.adoc[title]
+
+.Procedure
+
+. From the JupyterLab file-browser panel, drag the `1_experiment_train.ipynb` and `2_save_model.ipynb` notebooks onto the pipeline canvas.
++
+image::pipelines/wb-pipeline-drag-drop.png[ Drag and Drop Notebooks]
+
+. Click the output port of `1_experiment_train.ipynb` and drag a connecting line to the input port of `2_save_model.ipynb`.
++
+image::pipelines/wb-pipeline-connect-nodes.png[Connect Nodes, 400]
+
+. Save the pipeline.
+
+.Verification
+
+* Your pipeline has two nodes.
+
+.Next step
+
+xref:specifying-the-training-file-as-a-dependency.adoc[Specify the training file as a dependency]

workshop/docs/modules/ROOT/pages/automating-workflows-with-pipelines.adoc

@@ -1,227 +1,11 @@
+:_module-type: CONCEPT
+
 [id='automating-workflows-with-pipelines']
 = Automating workflows with data science pipelines
 
-In previous sections of this {deliverable}, you used a notebook to train and save your model. Optionally, you can automate these tasks by using {productname-long} pipelines. Pipelines offer a way to automate the execution of multiple notebooks and Python code. By using pipelines, you can execute long training jobs or retrain your models on a schedule without having to manually run them in a notebook.
-
-In this section, you create a simple pipeline by using the GUI pipeline editor. The pipeline uses the notebook that you used in previous sections to train a model and then save it to S3 storage.
-
-Your completed pipeline should look like the one in the `6 Train Save.pipeline` file.
-
-To explore the pipeline editor, complete the steps in the following procedure to create your own pipeline. Alternately, you can skip the following procedure and instead run the `6 Train Save.pipeline` file.
-
-== Prerequisites
-
-* You configured a pipeline server as described in xref:enabling-data-science-pipelines.adoc[Enabling data science pipelines].
-* If you configured the pipeline server after you created your workbench, you stopped and then started your workbench.
-
-== Create a pipeline
-
-. Open your workbench's JupyterLab environment. If the launcher is not visible, click *+* to open it.
-+
-image::pipelines/wb-pipeline-launcher.png[Pipeline buttons, 400]
-
-. Click *Pipeline Editor*.
-+
-image::pipelines/wb-pipeline-editor-button.png[Pipeline Editor button, 75]
-+
-You've created a blank pipeline.
-
-. Set the default runtime image for when you run your notebook or Python code.
-
-.. In the pipeline editor, click *Open Panel*.
-+
-image::pipelines/wb-pipeline-panel-button-loc.png[Open Panel,400]
-
-.. Select the *Pipeline Properties* tab.
-+
-image::pipelines/wb-pipeline-properties-tab.png[Pipeline Properties Tab]
-
-.. In the *Pipeline Properties* panel, scroll down to *Generic Node Defaults* and *Runtime Image*. Set the value to `Tensorflow with Cuda and Python 3.11 (UBI 9)`.
-+
-image::pipelines/wb-pipeline-runtime-image.png[Pipeline Runtime Image0, 400]
-
-. Select *File* -> *Save Pipeline*.
-
-== Add nodes to your pipeline
-
-Add some steps, or *nodes* in your pipeline. Your two nodes will use the  `1_experiment_train.ipynb` and `2_save_model.ipynb` notebooks.
-
-. From the file-browser panel, drag the `1_experiment_train.ipynb` and `2_save_model.ipynb` notebooks onto the pipeline canvas.
-+
-image::pipelines/wb-pipeline-drag-drop.png[ Drag and Drop Notebooks]
-
-. Click the output port of `1_experiment_train.ipynb` and drag a connecting line to the input port of `2_save_model.ipynb`.
-+
-image::pipelines/wb-pipeline-connect-nodes.png[Connect Nodes, 400]
-
-. Save the pipeline.
-
-== Specify the training file as a dependency
-
-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.
-
-. Click the `1_experiment_train.ipynb` node.
-+
-image::pipelines/wb-pipeline-node-1.png[Select Node 1, 150]
-
-. In the *Properties* panel, click the *Node Properties* tab.
-
-. Scroll down to the *File Dependencies* section and then click *Add*.
-+
-image::pipelines/wb-pipeline-node-1-file-dep.png[Add File Dependency, 500]
-
-. Set the value to `data/*.csv` which contains the data to train your model.
-
-. Select the *Include Subdirectories* option.
-+
-image::pipelines/wb-pipeline-node-1-file-dep-form.png[Set File Dependency Value, 300]
-
-. *Save* the pipeline.
-
-== Create and store the ONNX-formatted output file
-
-In node 1, the notebook creates the `models/fraud/1/model.onnx` file. In node 2, the notebook uploads that file to the S3 storage bucket. You must set `models/fraud/1/model.onnx` file as the output file for both nodes.
-
-. Select node 1.
-
-. Select the *Node Properties* tab.
-
-. Scroll down to the *Output Files* section, and then click *Add*.
-
-. Set the value to `models/fraud/1/model.onnx`.
-+
-image::pipelines/wb-pipeline-node-1-file-output-form.png[Set file dependency value, 400]
-
-. Repeat steps 2-4 for node 2.
-
-. *Save* the pipeline.
- 
-== Configure the connection to the S3 storage bucket
-
-In node 2, the notebook uploads the model to the S3 storage bucket.
-
-You must set the S3 storage bucket keys by using the secret created by the `My Storage` connection that you set up in the storing-data-with-connections.adoc[Storing data with connections] section of this {deliverable}.
-
-You can use this secret in your pipeline nodes without having to save the information in your pipeline code. This is important, for example, if you want to save your pipelines - without any secret keys - to source control.
-
-The secret is named `aws-connection-my-storage`. 
-
-[NOTE] 
-====
-If you named your 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 *Connections* tab. 
-
-image::pipelines/dsp-dc-secret-name.png[My Storage Secret Name, 400]
-====
-
-The `aws-connection-my-storage` secret includes the following fields:
-
-* `AWS_ACCESS_KEY_ID`
-* `AWS_DEFAULT_REGION`
-* `AWS_S3_BUCKET`
-* `AWS_S3_ENDPOINT`
-* `AWS_SECRET_ACCESS_KEY`
-
-You must set the secret name and key for each of these fields.
-
-.Procedure
-
-. Remove any pre-filled environment variables.
-
-.. Select node 2, and then select the *Node Properties* tab.
-+
-Under *Additional Properties*, note that some environment variables have been pre-filled. The pipeline editor inferred that you need them from the notebook code.  
-+
-Since you don't want to save the value in your pipelines, remove all of these environment variables.
-
-.. Click *Remove* for each of the pre-filled environment variables.
-+
-image::pipelines/wb-pipeline-node-remove-env-var.png[Remove Env Var]
-
-. Add the S3 bucket and keys by using the Kubernetes secret.
-
-.. Under *Kubernetes Secrets*, click *Add*.
-+
-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`
-** *Secret Name*: `aws-connection-my-storage`
-** *Secret Key*: `AWS_ACCESS_KEY_ID`
-+
-image::pipelines/wb-pipeline-kube-secret-form.png[Secret Form, 400]
-
-. Repeat Step 2 for each of the following Kubernetes secrets:
-
-* *Environment Variable*: `AWS_SECRET_ACCESS_KEY`
-** *Secret Name*: `aws-connection-my-storage`
-** *Secret Key*: `AWS_SECRET_ACCESS_KEY`
-
-* *Environment Variable*: `AWS_S3_ENDPOINT`
-** *Secret Name*: `aws-connection-my-storage`
-** *Secret Key*: `AWS_S3_ENDPOINT`
-
-* *Environment Variable*: `AWS_DEFAULT_REGION`
-** *Secret Name*: `aws-connection-my-storage`
-** *Secret Key*: `AWS_DEFAULT_REGION`
-
-* *Environment Variable*: `AWS_S3_BUCKET`
-** *Secret Name*: `aws-connection-my-storage`
-** *Secret Key*: `AWS_S3_BUCKET`
-
-. Select *File* -> *Save Pipeline As* to save and rename the pipeline. For example, rename it to `My Train Save.pipeline`.
-
-== Run the Pipeline 
-
-Upload the pipeline on your cluster and run it. You can do so directly from the pipeline editor. You can use your own newly created pipeline or the pipeline in the provided `6 Train Save.pipeline` file.
-
-.Procedure
-
-. Click the play button in the toolbar of the pipeline editor.
-+
-image::pipelines/wb-pipeline-run-button.png[Pipeline Run Button, 300]
-
-. Enter a name for your pipeline.
-. Verify that the *Runtime Configuration:* is set to `Data Science Pipeline`.  
-. Click *OK*.
-+
-[NOTE]
-====
-If you see an error message stating that "no runtime configuration for Data Science Pipeline is defined", you might have created your workbench before the pipeline server was available. 
-
-To address this situation, you must verify that you configured the pipeline server and then restart the workbench.
-
-Follow these steps in the {productname-short} dashboard:
-
-. Check the status of the pipeline server:
-.. In your Fraud Detection project, click the *Pipelines* tab.
-** If you see the *Configure pipeline server* option, follow the steps in xref:enabling-data-science-pipelines.adoc[Enabling data science pipelines]. 
-** If you see the *Import a pipeline* option, the pipeline server is configured. Continue to the next step.
-. Restart your Fraud Detection workbench:
-.. Click the *Workbenches* tab.
-.. Click *Stop* and then click *Stop workbench*. 
-.. After the workbench status is *Stopped*, click *Start*.
-.. Wait until the workbench status is *Running*.
-. Return to your workbench's JupyterLab environment and run the pipeline. 
-====
-
-. In the {productname-short} dashboard, open your data science project and expand the newly created pipeline.
-+
-image::pipelines/dsp-pipeline-complete.png[New pipeline expanded, 800]
-
-. Click *View runs*.
-+
-image::pipelines/dsp-view-run.png[View runs for selected pipeline, 500]
-
-. Click your run and then view the pipeline run in progress.
-+
-image::pipelines/pipeline-run-complete.png[Pipeline run progress, 800]
-
-The result should be a `models/fraud/1/model.onnx` file in your S3 bucket which you can serve, just like you did manually in the xref:preparing-a-model-for-deployment.adoc[Preparing a model for deployment] section.
-
+[role="_abstract"]
+Earlier, you used a notebook to train and save your model. Optionally, you can automate these tasks by using {productname-long} pipelines. Pipelines offer a way to automate the execution of many notebooks and Python code. By using pipelines, you can run long training jobs or retrain your models on a schedule without having to manually run them in a notebook.
 
-.Next step
+To explore the pipeline editor, complete the steps in the following procedures to create your own pipeline. 
 
-(Optional) xref:running-a-pipeline-generated-from-python-code.adoc[Running a data science pipeline generated from Python code]
+Alternately, you can skip the following procedures and instead run the `6 Train Save.pipeline` file.

workshop/docs/modules/ROOT/pages/conclusion.adoc

@@ -1,15 +1,18 @@
+:_module-type: CONCEPT
+
 = Fraud Detection Workshop with {productname-long}
 :page-layout: home
 :!sectids:
 
 [.text-center.strong]
 == Conclusion
 
+[role="_abstract"]
 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:
 
 * Explored a pre-trained fraud detection model by using a Jupyter notebook.
 * Deployed the model by using {productname-short} model serving.
 * Refined and trained the model by using automated pipelines.
-* Learned how to train the model by using Ray, a distributed computing framework.
+* Learned how to train the model by using distributed computing frameworks.

workshop/docs/modules/ROOT/pages/configuring-the-connection-to-storage.adoc

@@ -0,0 +1,91 @@
+:_module-type: PROCEDURE
+
+[id='configuring-the-connection-to-storage']
+= Configuring the connection to storage
+
+[role="_abstract"]
+In node 2, the notebook uploads the model to the S3 storage bucket. You must set the S3 storage bucket keys by using the secret created by the `My Storage` connection that you set up in xref:storing-data-with-connections.adoc[Storing data with connections].
+
+You can use this secret in your pipeline nodes without having to save the information in your pipeline code. This is important, for example, if you want to save your pipelines - without any secret keys - to source control.
+
+The name of the secret is `aws-connection-my-storage`. 
+
+[NOTE] 
+====
+If you named your 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 *Connections* tab. 
+
+image::pipelines/dsp-dc-secret-name.png[My Storage Secret Name, 400]
+====
+
+The `aws-connection-my-storage` secret includes the following fields:
+
+* `AWS_ACCESS_KEY_ID`
+* `AWS_DEFAULT_REGION`
+* `AWS_S3_BUCKET`
+* `AWS_S3_ENDPOINT`
+* `AWS_SECRET_ACCESS_KEY`
+
+You must set the secret name and key for each of these fields.
+
+.Prerequisites
+
+*  You created the `My Storage` connection, as described in xref:storing-data-with-connections.adoc[Storing data with connections].
+
+* You set the `models/fraud/1/model.onnx` file as the output file for both nodes in your pipeline, as described in
+xref:creating-and-storing-the-onnx-output-file.adoc[Creating and storing the ONNX-formatted output file].
+
+.Procedure
+
+. Remove any pre-filled environment variables.
+
+.. Select node 2, and then select the *Node Properties* tab.
++
+Under *Additional Properties*, note that some environment variables have been pre-filled. The pipeline editor inferred that you need them from the notebook code.  
++
+Because you do not want to save the value in your pipelines, remove all of these environment variables.
+
+.. Click *Remove* for each of the pre-filled environment variables.
++
+image::pipelines/wb-pipeline-node-remove-env-var.png[Remove Env Var]
+
+. Add the S3 bucket and keys by using the Kubernetes secret.
+
+.. Under *Kubernetes Secrets*, click *Add*.
++
+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`
+** *Secret Name*: `aws-connection-my-storage`
+** *Secret Key*: `AWS_ACCESS_KEY_ID`
++
+image::pipelines/wb-pipeline-kube-secret-form.png[Secret Form, 400]
+
+. Repeat Step 2 for each of the following Kubernetes secrets:
+
+* *Environment Variable*: `AWS_SECRET_ACCESS_KEY`
+** *Secret Name*: `aws-connection-my-storage`
+** *Secret Key*: `AWS_SECRET_ACCESS_KEY`
+
+* *Environment Variable*: `AWS_S3_ENDPOINT`
+** *Secret Name*: `aws-connection-my-storage`
+** *Secret Key*: `AWS_S3_ENDPOINT`
+
+* *Environment Variable*: `AWS_DEFAULT_REGION`
+** *Secret Name*: `aws-connection-my-storage`
+** *Secret Key*: `AWS_DEFAULT_REGION`
+
+* *Environment Variable*: `AWS_S3_BUCKET`
+** *Secret Name*: `aws-connection-my-storage`
+** *Secret Key*: `AWS_S3_BUCKET`
+
+. Select *File* -> *Save Pipeline As* to save and rename the pipeline. For example, rename it to `My Train Save.pipeline`.
+
+.Verification
+
+* You set the S3 storage bucket keys by using the secret created by the `My Storage` connection.
+
+.Next step
+
+xref:running-your-pipeline.adoc[Running your pipeline]