AAP-36632: Restructure the Lightspeed User Guide

lightspeed/assemblies/assembly_administering_ansible_lightspeed.adoc

@@ -0,0 +1,41 @@
+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_ansible-content-parser.adoc[leveloffset=+1]
+include::modules/proc_install-content-parser.adoc[leveloffset=+2]
+include::modules/proc_generate-training-data-set.adoc[leveloffset=+2]
+include::modules/proc_view-content-parser-output.adoc[leveloffset=+2]
+include::modules/proc_resolve-ansible-lint-rule-violations.adoc[leveloffset=+2]
+include::modules/proc_merge-multiple-jsonl-files.adoc[leveloffset=+2]
+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,40 @@
+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
+* Create roles (TBD)
+* 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_overview-and-best-practices.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-best-practices.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/attributes/attributes.adoc

@@ -26,6 +26,7 @@
 :LightspeedShortName: Red Hat Ansible Lightspeed
 :LightspeedTechPreview: Ansible Lightspeed Technical Preview
 :AnsibleCodeBot: Ansible code bot
+:AnsibleVSCode: Ansible VS Code extension
 :AnsibleContentParser: content parser tool
 :ibmwatsonxcodeassistant: IBM watsonx Code Assistant
 :ibmCPD: {ibmwatsonxcodeassistant} for {LightspeedshortName} on Cloud Pak for Data

lightspeed/modules/con_ansible-content-parser.adoc

@@ -2,13 +2,39 @@
 
 [id="ansible-content-parser_{context}"]
 
-= Creating a training data set by using the {AnsibleContentParser}
+= Configuring custom models
+
+:context: configuring-custom-models
 
 [role="_abstract"]
 
+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_configuring-custom-models[Create a training data set by using the {AnsibleContentParser}]
+
+. xref:create-deploy-custom-model-ibm_configuring-custom-models[Create and deploy a custom model by using {ibmwatsonxcodeassistant}]
+
+. xref:configure-custom-models-lightspeed_configuring-custom-models[Configure {LightspeedshortName} to use the custom model]
+
+== Creating a training data set by using the {AnsibleContentParser}
+
 Use the {AnsibleContentParser}, a command-line interface (CLI) tool, to scan your existing Ansible files and generate a custom model training data set. The training data set includes a list of Ansible files and their paths relative to the project root. You can then upload this data set to {ibmwatsonxcodeassistant}, and use it to create a custom model that is trained on your organization's existing Ansible content. 
 
-== Methods of creating training data sets
+=== Methods of creating training data sets
 You can generate a training data set by using one of the following methods:  
 
 * *With ansible-lint preprocessing* 

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

@@ -0,0 +1,20 @@
+:_content-type: CONCEPT
+
+[id="con-configure-vs-code-extension_{context}"]
+
+= Installing and configuring the Ansible VS Code extension
+
+:context: con-configure-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:configuring-custom-models_set-up-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,15 @@
+:_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_overview-and-best-practices.adoc

@@ -1,7 +1,9 @@
 :_content-type: CONCEPT
 
 [id="overview-and-best-practices_{context}"]
-= Overview
+= 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_playbook-generation-best-practices.adoc

@@ -1,7 +1,19 @@
 :_content-type: CONCEPT
 
 [id="playbook-generation-best-practices_{context}"]
-= Best practices to generate playbooks 
+
+= 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.
 

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

@@ -0,0 +1,52 @@
+:_content-type: CONCEPT
+
+[id="con-administer-admin-dashboard-telemetry_{context}"]
+
+= Viewing and managing Admin dashboard telemetry
+
+:context: managing-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

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

@@ -0,0 +1,27 @@
+:_content-type: PROCEDURE
+
+[id="logging-into-portal-auto-dev_{context}"]
+
+= Logging in to the Ansible Lightspeed portal
+
+.Procedure
+
+. Go to the link:https://c.ai.ansible.redhat.com/[Ansible Lightspeed portal login page].
+. Click menu:Log in[Log in with Red Hat].
+. Enter your Red Hat account username and password.
+
+On successful authentication, the login screen is displayed along with your username and your assigned user role.
+
+= Logging out of the Ansible Lightspeed Service
+
+[role="_abstract"]
+To log out of the Ansible Lightspeed Service, you must log out of both the Ansible Lightspeed VS Code extension and the Ansible Lightspeed portal.
+
+.Procedure
+
+* Log out of the Ansible Lightspeed VS Code extension:
+** Click the *Person* icon image:person-icon-vs-code.png[Person icon]. You will see a list of accounts that VS Code is logged into.
+** Select menu:Ansible Lightspeed[Sign Out].
+* Log out of the Ansible Lightspeed portal:
+** Navigate to the link:https://c.ai.ansible.redhat.com/[Ansible Lightspeed portal login page].
+** Click *Log out*.

lightspeed/titles/lightspeed-user-guide/master.adoc

@@ -15,10 +15,7 @@ include::aap-common/making-open-source-more-inclusive.adoc[leveloffset=+1]
 include::assemblies/assembly-lightspeed-intro.adoc[leveloffset=+1]
 include::assemblies/assembly_starting-lightspeed-trial.adoc[leveloffset=+1]
 include::assemblies/assembly_setting-up-lightspeed.adoc[leveloffset=+1]
-include::assemblies/assembly_logging-in-out-portal.adoc[leveloffset=+1]
-include::assemblies/assembly_configuring-vscode-extension.adoc[leveloffset=+1]
-include::assemblies/assembly_requesting-task-recommendations.adoc[leveloffset=+1]
-include::assemblies/assembly_generating-playbooks.adoc[leveloffset=+1]
+include::assemblies/assembly_developing_ansible_content.adoc[leveloffset=+1]
+include::assemblies/assembly_administering_ansible_lightspeed.adoc[leveloffset=+1]
 include::assemblies/assembly_using-code-bot-for-suggestions.adoc[leveloffset=+1]
-include::assemblies/assembly_managing-admin-dashboard-telemetry.adoc[leveloffset=+1]
 include::assemblies/assembly_troubleshooting-lightspeed.adoc[leveloffset=+1]