AAP-36632-update: TOC restructure of Ansible Lightspeed User Guide

lightspeed/assemblies/assembly_generating-playbooks.adoc → lightspeed/archive/archived-assemblies/assembly_generating-playbooks.adoc

@@ -19,7 +19,7 @@ These capabilities enable Ansible developers to use natural language prompts to
 You can generate playbooks and view playbook explanations when connecting to the {LightspeedShortName} cloud service and on-premise deployments.
 ====
 
-include::modules/con_playbook-generation-best-practices.adoc[leveloffset=+1]
+include::modules/con_playbook-generation.adoc[leveloffset=+1]
 include::modules/proc_generate-playbook.adoc[leveloffset=+1]
 include::modules/proc_view-playbook-explanation.adoc[leveloffset=+1]
 

lightspeed/assemblies/assembly_requesting-task-recommendations.adoc → lightspeed/archive/archived-assemblies/assembly_requesting-task-recommendations.adoc

@@ -12,7 +12,7 @@ ifdef::context[:parent-context: {context}]
 
 {LightspeedshortName} is integrated into Visual Studio (VS) Code through the Ansible VS Code extension. You can request code recommendations for your task intent by using Ansible VS Code extension.
 
-include::modules/con_overview-and-best-practices.adoc[leveloffset=+1]
+include::modules/con_task-recommendations.adoc[leveloffset=+1]
 include::modules/proc_single-task-recs.adoc[leveloffset=+1]
 include::modules/proc_multi-task-recs.adoc[leveloffset=+1]
 include::modules/proc_view-training-matches.adoc[leveloffset=+1]

lightspeed/assemblies/assembly_administering-ansible-lightspeed.adoc

@@ -0,0 +1,40 @@
+ifdef::context[:parent-context: {context}]
+
+:_content-type: ASSEMBLY
+
+[id="administering-ansible-lightspeed_{context}"]
+
+= Administering the Ansible Lightspeed Service
+
+:context: administering-ansible-lightspeed
+
+[role="_abstract"]
+
+As a platform administrator, Ansible Automation Platform can help you enable your users and teams to develop and run automation.
+
+This guide walks you through the basic steps to get set up as an administrator for Ansible Automation Platform, including configuring and maintaining the platform for users.
+
+As an organization administrator, you can use {LightspeedShortName} to manage the Ansible Lightspeed service, so that your users and teams can create and use custom automation content. This chapter provides information about how to get set up as an organization administrator on {LightspeedShortName}, with details on how to:
+
+* Access the Ansible Lightspeed portal as an organization administrator
+* View and manage the Admin dashboard telemetry data
+* Configure custom models
+
+include::modules/proc_log-in-administrator-portal.adoc[leveloffset=+1]
+include::modules/proc_log-out-of-portal.adoc[leveloffset=+2]
+include::modules/con_view-manage-admin-dashboard-telemetry.adoc[leveloffset=+1]
+include::modules/proc_view-admin-dashboard.adoc[leveloffset=+2]
+include::modules/proc_disable-admin-dashboard-telemetry.adoc[leveloffset=+2]
+include::modules/con_config-custom-models.adoc[leveloffset=+1]
+include::modules/con_ansible-content-parser.adoc[leveloffset=+2]
+include::modules/proc_install-content-parser.adoc[leveloffset=+3]
+include::modules/proc_generate-training-data-set.adoc[leveloffset=+3]
+include::modules/proc_view-content-parser-output.adoc[leveloffset=+3]
+include::modules/proc_resolve-ansible-lint-rule-violations.adoc[leveloffset=+3]
+include::modules/proc_merge-multiple-jsonl-files.adoc[leveloffset=+3]
+include::modules/proc_create-deploy-custom-model-ibm.adoc[leveloffset=+2]
+include::modules/proc_configure-custom-models-lightspeed.adoc[leveloffset=+2]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
+

lightspeed/assemblies/assembly_developing-ansible-content.adoc

@@ -0,0 +1,38 @@
+ifdef::context[:parent-context: {context}]
+
+:_content-type: ASSEMBLY
+
+[id="developing-ansible-content_{context}"]
+= Developing Ansible content
+
+:context: developing-ansible-content
+
+[role="_abstract"]
+
+As an automation developer, you can use {LightspeedShortName} to implement your organization’s automation strategy. {LightspeedShortName} can help you create and use custom automation content. This chapter provides information about how to get set up as an automation developer on {LightspeedShortName}, with details on how to:
+
+* Access the Ansible Lightspeed portal as an automation developer
+* Install and configure the {AnsibleVSCode}
+* Create task recommendations
+* Create playbooks and view playbook explanations
+* Provide feedback on the Ansible Lightspeed service
+
+include::modules/con_log-into-portal-auto-dev.adoc[leveloffset=+1]
+include::modules/proc_log-into-portal-auto-dev.adoc[leveloffset=+2]
+include::modules/con_config-vs-code-extension.adoc[leveloffset=+1]
+include::modules/proc_install-vscode-extension.adoc[leveloffset=+2]
+include::modules/proc_configure-vscode-extension.adoc[leveloffset=+2]
+include::modules/proc_login-vscode-extension.adoc[leveloffset=+2]
+include::modules/proc_log-out-of-portal.adoc[leveloffset=+2]
+include::modules/con_task-recommendations.adoc[leveloffset=+1]
+include::modules/proc_single-task-recs.adoc[leveloffset=+2]
+include::modules/proc_multi-task-recs.adoc[leveloffset=+2]
+include::modules/proc_view-training-matches.adoc[leveloffset=+2]
+include::modules/con_playbook-generation.adoc[leveloffset=+1]
+include::modules/proc_generate-playbook.adoc[leveloffset=+2]
+include::modules/proc_view-playbook-explanation.adoc[leveloffset=+2]
+include::modules/proc_provide-feedback.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
+

lightspeed/assemblies/assembly_setting-up-lightspeed.adoc

@@ -21,7 +21,6 @@ As a Red Hat customer portal administrator, you must configure {LightspeedShortN
 include::modules/con_wca-key-model-id.adoc[leveloffset=+1]
 include::assembly_configure-code-assistant.adoc[leveloffset=+1]
 include::assembly_configuring-lightspeed-onpremise.adoc[leveloffset=+1]
-include::assembly_configuring-custom-models.adoc[leveloffset=+1]
 
 // The nested assemblies use this current assembly as their parent,
 // so the value of parent-context was changed.

lightspeed/modules/con_ansible-content-parser.adoc

@@ -30,12 +30,12 @@ The {AnsibleContentParser} scans the following directories and file formats:
 == Process of creating a training data set
 To create a custom model training data set, perform the following tasks:
 
-. xref:install-content-parser_configuring-custom-models[Install the {AnsibleContentParser} on your computer]
+. xref:install-content-parser_administering-ansible-lightspeed[Install the {AnsibleContentParser} on your computer]
 
-. xref:generate-training-data-set_configuring-custom-models[Generate a custom model training data set]
+. xref:generate-training-data-set_administering-ansible-lightspeed[Generate a custom model training data set]
 
-. xref:view-content-parser-output_configuring-custom-models[View the generated training data set]
+. xref:view-content-parser-output_administering-ansible-lightspeed[View the generated training data set]
 
-. (Optional: If you generated a training data set with ansible-lint preprocessing and detected ansible-lint rule violations) xref:resolve-ansible-lint-rule-violations_configuring-custom-models[Resolve ansible-lint rule violations]
+. (Optional: If you generated a training data set with ansible-lint preprocessing and detected ansible-lint rule violations) xref:resolve-ansible-lint-rule-violations_administering-ansible-lightspeed[Resolve ansible-lint rule violations]
 
-. (Optional: If you generated multiple training data sets) xref:merge-multiple-jsonl-files_configuring-custom-models[Merge multiple training data sets into a single JSONL file]
+. (Optional: If you generated multiple training data sets) xref:merge-multiple-jsonl-files_administering-ansible-lightspeed[Merge multiple training data sets into a single JSONL file]

lightspeed/modules/con_config-custom-models.adoc

@@ -0,0 +1,28 @@
+:_content-type: CONCEPT
+
+[id="configure-custom-models_{context}"]
+
+= Configuring custom models
+
+
+As an organization administrator, you can create and use fine-tuned, custom models that are trained on your organization's existing Ansible content. With this capability, you can tune the models to your organization's automation patterns and improve the code recommendation experience.
+
+After you create a custom model, you can specify one of the following access types:
+
+* Enable access for all users in your organization
++
+You can configure the custom model as the default model for your organization. All users in your organization can use the custom model.
+
+* Enable access for select Ansible users in your organization
++
+Using the *model-override* setting in the Ansible VS Code extension, select Ansible users can tune their Ansible Lightspeed service to use a custom model instead of the default model. 
+
+== Process for configuring custom models
+
+To configure a custom model, perform the following tasks: 
+
+. xref:ansible-content-parser_administering-ansible-lightspeed[Create a training data set by using the {AnsibleContentParser}]
+
+. xref:create-deploy-custom-model-ibm_administering-ansible-lightspeed[Create and deploy a custom model by using {ibmwatsonxcodeassistant}]
+
+. xref:configure-custom-models-lightspeed_administering-ansible-lightspeed[Configure {LightspeedshortName} to use the custom model]

lightspeed/modules/con_config-vs-code-extension.adoc

@@ -0,0 +1,19 @@
+:_content-type: CONCEPT
+
+[id="con-configure-vs-code-extension_{context}"]
+
+= Installing and configuring the Ansible VS Code extension
+
+
+{LightspeedFullName} is integrated with the Ansible Visual Studio (VS) Code extension in VS Code. The Ansible VS Code extension, with {LightspeedShortName} features enabled, automatically collects recommendations, usage telemetry, and Ansible YAML file state through automated events. 
+
+To access {LightspeedShortName}, all Ansible users must install and configure the Ansible VS Code extension in their VS Code. The Ansible VS Code extension uses the Ansible-specific IBM watsonx Granite model configured in the {LightspeedShortName} administrator portal as the default mode for all users in your organization. 
+
+You can also use a custom, fine-tuned model if your organization administrator has created a custom model and has shared the model ID with you separately. Use the *model-override* setting in the Ansible VS Code extension to override the default model, and use the custom model instead. Using a custom model enables you to improve the code recommendation experience and tune the model to your organizational automation patterns. For example, if you are using {LightspeedShortName} both as an organization administrator and a user, you can test the custom model for select Ansible users before making it available for all users in your organization. For more information, see xref:configure-custom-models_administering-ansible-lightspeed[Configuring custom models]. 
+
+== Connectivity requirements
+To generate code recommendations, the Ansible Lightspeed service in Visual Studio (VS) Code editor requires access to the following outbound domain:
+
+* https://c.ai.ansible.redhat.com
+
+The outbound connections are encrypted on TCP protocol port 443.

lightspeed/modules/con_log-into-portal-auto-dev.adoc

@@ -0,0 +1,17 @@
+:_content-type: CONCEPT
+
+[id="log-into-portal-auto-dev_{context}"]
+
+= Accessing the Ansible Lightspeed portal as an automation developer
+
+
+You can access {LightspeedShortName} through the link:https://c.ai.ansible.redhat.com/[Ansible Lightspeed portal]. After you enter your {RHSSO} ({RHSSOshort}) account credentials, your account is authenticated and you are granted access. Your assigned user role is displayed on the login screen of the Ansible Lightspeed portal. 
+
+.User login scenarios
+[cols="50%,50%",options="header"]
+|====
+| *Scenario* | *Result*
+|You are a {RHSSOshort} user. +
+NOTE: This is the typical scenario for accessing {LightspeedShortName} as an Ansible user.| You are routed to the {LightspeedShortName} paid commercial offering.
+|You are a {RHSSOshort} user, but your organization administrator has not configured {LightspeedShortName} to connect with {ibmwatsonxcodeassistant}.| You are routed to the {LightspeedShortName} paid commercial offering with a message that your organization administrator has not configured a model for your organization.
+|====

lightspeed/modules/con_playbook-generation.adoc

@@ -0,0 +1,35 @@
+:_content-type: CONCEPT
+
+[id="playbook-generation_{context}"]
+= Creating playbooks and viewing playbook explanations 
+
+Using the Ansible VS Code extension, you can create Ansible playbooks using a natural language interface in English. {LightspeedFullName} reads the natural language prompts and generates an entire playbook recommendation based on your intent. You can also view the explanations for new or existing playbooks. The playbook explanations describe what the playbook does and contextualize its impact.
+
+These capabilities enable Ansible developers to use natural language prompts to create new Ansible playbooks quickly and more efficiently and also get an explanation for existing Ansible playbook, thereby reducing the overall onboarding learning period. For information about Ansible playbooks, see the link:https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/2.4/html/getting_started_with_ansible_playbooks/index[Getting started with Ansible Playbooks] guide.
+
+[NOTE]
+====
+You can create playbooks and view playbook explanations when connecting to the {LightspeedShortName} cloud service and on-premise deployments.
+====
+
+== Best practices to create playbooks 
+
+Follow these guidelines for the highest quality of a playbook recommendation.
+
+* Ensure that the goal statements directly specify what the playbook must do.
++
+Your statement should start with the goal of the playbook, for example, `Apply security patches to RHEL9`. Avoid starting statements with `Create a playbook that`, `Please prepare a playbook that`, or `I need help with`. 
+
+* Ensure that the goal statement does not contain new lines.
+
+* Ensure that the goal statement is not more than one sentence.
++
+You might have to repeat the details in the goal statement to produce the best results. It is recommended that you use the generated outline as feedback about whether your goal statement might benefit from more or less details, and then modify the goal statement as necessary.  
+
+* Ensure the following when you edit the outline:
+
+** Do not restate the goal of the playbook.
+
+** Verify that the steps considered capture the key steps in the playbook. The steps need not reflect each and every task that is expected in the playbook.
+
+** Keep the step description in one sentence without adding new lines to the outline.

lightspeed/modules/con_overview-and-best-practices.adoc → lightspeed/modules/con_task-recommendations.adoc

@@ -1,7 +1,9 @@
 :_content-type: CONCEPT
 
-[id="overview-and-best-practices_{context}"]
-= Overview
+[id="con-task-recommendations_{context}"]
+= Creating task recommendations
+
+{LightspeedshortName} is integrated into Visual Studio (VS) Code through the Ansible VS Code extension. You can request code recommendations for your task intent by using Ansible VS Code extension.
 
 You can perform the following tasks from the Ansible VS Code extension: 
 

lightspeed/modules/con_telemetry-data-collection-notice.adoc

@@ -27,7 +27,7 @@ This includes the following data:
 ** Prompts and content suggestions, including accept or reject of the content suggestions
 ** User sentiment feedback
 +
-You can also disable the Admin dashboard telemetry if you no longer want to collect and monitor the telemetry data. For more information about Admin dashboard telemetry, see xref:managing-admin-dashboard-telemetry_lightspeed-user-guide[Viewing and managing Admin dashboard telemetry].
+You can also disable the Admin dashboard telemetry if you no longer want to collect and monitor the telemetry data. For more information about Admin dashboard telemetry, see xref:view-manage-admin-dashboard-telemetry_administering-ansible-lightspeed[Viewing and managing Admin dashboard telemetry].
 
 [NOTE]
 ====
@@ -50,4 +50,4 @@ Red Hat may share telemetry data with its business partners in an aggregated for
 Red Hat may engage certain service providers to assist in the collection and storage of the telemetry data.
 
 === User Control/ Enabling and Disabling Admin Dashboard Telemetry Collection
-You cannot disable collection of operational telemetry data. Operational telemetry data includes only data that is necessary to operate and troubleshoot the service. However, you can disable the collection of Admin Dashboard telemetry data. For more information, see xref:disable-admin-dashboard-telemetry_managing-admin-dashboard-telemetry[Disabling the Admin dashboard telemetry]. 
+You cannot disable collection of operational telemetry data. Operational telemetry data includes only data that is necessary to operate and troubleshoot the service. However, you can disable the collection of Admin Dashboard telemetry data. For more information, see xref:disable-admin-dashboard-telemetry_administering-ansible-lightspeed[Disabling the Admin dashboard telemetry]. 

lightspeed/modules/con_view-manage-admin-dashboard-telemetry.adoc

@@ -0,0 +1,51 @@
+:_content-type: CONCEPT
+
+[id="view-manage-admin-dashboard-telemetry_{context}"]
+
+= Viewing and managing the Admin dashboard telemetry
+
+
+{LightspeedshortName} collects the following telemetry data by default:
+
+* *Operational telemetry data*
++
+This is the data that is required to operate and troubleshoot the Ansible Lightspeed service. For more information, refer the Enterprise Agreement. You cannot disable the collection of operational telemetry data. 
++
+This includes the following data:
+
+** Organization you are logged into (Organization ID, account number)
+** Large language model (or models) that you are connected to 
+
+* *Admin dashboard telemetry data*
++
+This is the data that provides insight into how your organization users are using the Ansible Lightspeed service, and the metrics are displayed on the Admin dashboard. 
++
+This includes the following data:
+
+** Prompts and content suggestions, including accept or reject of the content suggestions
+** User sentiment feedback
++
+You can also disable the Admin dashboard telemetry if you no longer want to collect and monitor the telemetry data. 
+
+[NOTE]
+====
+Viewing telemetry data on the Admin dashboard is not yet supported on {LightspeedShortName} on-premise deployments.
+====
+
+== Prerequisites
+To view and manage the Admin dashboard telemetry data, ensure that you have the following:
+
+* You have organization administrator privileges to a Red Hat Customer Portal organization with a valid Red Hat Ansible Automation Platform subscription.
+
+* You have installed the Ansible VS Code extension v2.13.148 that is required to collect Admin dashboard telemetry. 
+
+IMPORTANT: {LightspeedshortName} does not collect users' personal information, such as usernames or passwords. If any personal information is inadvertently received, the data is deleted. For more information about {LightspeedshortName}'s privacy practices, see the xref:telemetry-data-collection-notice_lightspeed-intro[Telemetry Data Collection Notice for the Admin dashboard].
+
+== What telemetry data is collected?
+Following is the list of telemetry data that {LightspeedshortName} collects:
+
+* Details of the organization that you are logged into, such as organization ID and account number
+* Large language models that you are connected to 
+* Inline suggestions that were accepted, rejected, or ignored by your organization users
+* User sentiment feedback
+* Top 10 modules returned in code recommendations