Update deployment troubleshooting and improve UX analysis panel docs

README.md

@@ -13,7 +13,7 @@
   - [Configuring ENV parameters](./docs/deployment/deployment.md#configure-env-files)
   - [Authenticating to Azure](./docs/deployment/deployment.md#log-into-azure-using-the-azure-cli)
   - [Deploying to Azure](./docs/deployment/deployment.md#deploy-and-configure-azure-resources)
-  - [Troubleshooting Deployment & Startup Issues](./docs/deployment/worbook_usage.md)
+  - [Troubleshooting Common Issues](./docs/deployment/troubleshooting.md)
   - [Considerations for Production Adoption](./docs/deployment/considerations_production.md)
 - [Enabling optional features](./docs/features/optional_features.md)
 - [Using the app](/docs/deployment/using_ia_first_time.md)

docs/deployment/deployment.md

@@ -44,10 +44,10 @@ Inside your Development environment (GitHub Codespaces or Container), do the fol
 
 Variable | Required | Description
 --- | --- | ---
-LOCATION | Yes | The location (West Europe is the default). The BICEP templates use this value.
-WORKSPACE | Yes  | The workspace name (use something simple and unique to you). This will appended to infoasst-????? in your subscription.
-SUBSCRIPTION_ID | Yes | The GUID that represents the Azure Subscription you want the Accelerator to be deployed into.
-TENANT_ID | Yes | The GUID that represents the Azure Active Directory Tenant for the Subscription you want the accelerator to be deployed into.
+LOCATION | Yes | The location (West Europe is the default). The BICEP templates use this value. To get a list of all the current Azure regions you can run `az account list-locations -o table`. The value here needs to be the *Name* value and not *Display Name*.
+WORKSPACE | Yes  | The workspace name (use something simple and unique to you). This will appended to infoasst-????? as the name of the resource group created in your subscription.
+SUBSCRIPTION_ID | Yes | The GUID that represents the Azure Subscription you want the Accelerator to be deployed into. This can be obtained from the *Subscription* blade in the Azure Portal.
+TENANT_ID | Yes | The GUID that represents the Azure Active Directory Tenant for the Subscription you want the accelerator to be deployed into. This can be obtained from the *Tenant Info* blade in the Azure Portal.
 IS_USGOV_DEPLOYMENT | Yes | Defaults to false. This value should be set to true only if you are deploying to one of the US Sovereign regions. Find more information on [Sovereign Deployment](./enable_sovereign_deployment.md)
 REQUIRE_WEBSITE_SECURITY_MEMBERSHIP | Yes | Use this setting to determine whether a user needs to be granted explicit access to the website via an Azure AD Enterprise Application membership (true) or allow the website to be available to anyone in the Azure tenant (false). Defaults to false. If set to true, A tenant level administrator will be required to grant the implicit grant workflow for the Azure AD App Registration manually.
 SKIP_PLAN_CHECK | No | If this value is set to 1, then the BICEP deployment will not stop to allow you to review the planned changes. The default value is 0 in the scripts, which will allow the deployment to stop and confirm you accept the proposed changes before continuing.

docs/deployment/statusdb_cosmos.md

@@ -0,0 +1,34 @@
+# Investigating File Processing Errors in CosmosDB Logs
+
+## Navigating to Azure Resource Group and Opening Cosmos Account Resource
+
+>1. Log in to the Azure portal.
+>2. In the left-hand menu, click on "Resource groups".
+>3. Select the desired resource group from the list.
+>4. In the resource group overview, locate and click on the Cosmos account resource.
+
+![CosmosDB Azure Portal Blade View](/docs/images/cosmos_account.png)
+
+## Accessing Data Explorer
+
+>1. Once you are on the Cosmos account resource page, navigate to the left-hand menu.
+>2. Under the "Settings" section, click on "Data Explorer".
+
+![CosmosDB Azure Portal Data Explorer View](/docs/images/data_explorer.png)
+
+## Expanding the Database
+
+>1. In the Data Explorer, you will see a list of databases associated with the Cosmos account.
+>2. Locate the "statusdb" database and click on it to expand.
+
+## Viewing the Items Table
+
+>1. Within the expanded "statusdb" database, you will find a list of containers (tables).
+>2. Look for the "items" table and click on it.
+
+## Checking File Processing Status and Errors
+
+>1. Once you are on the "items" table page, you will see a list of items (documents) in the table.
+>2. Each item represents a file being processed.
+>3. Look for the "status" field to see the status of each file being processed.
+>4. If there are any associated errors, they will be displayed in the "errors" field.

docs/deployment/troubleshooting.md

@@ -0,0 +1,29 @@
+# Troubleshooting
+
+## Infrastructure Deployment
+
+Please see below sections for troubleshooting the solution depending on what area of the process that is giving issue.
+
+If you are having issues with infrastructure deployment then the errors should be apparent in the make deploy output.
+
+You can also navigate to the Subscription in Azure portal, click the option for "Deployments" and find your deployment and related details and errors there.
+
+Take the full error and logs and post them to this GitHub repo Issues tab with your configuration used.
+
+More info can be found [here](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deployment-history?tabs=azure-portal)
+
+## File Processing
+
+If you encounter issues processing file(s) then you will want to look at CosmosDB. StatusDB's items table will hold a step by step status of each file.
+Check out this section for more details [CosmosDB Usage](/docs/deployment/statusdb_cosmos.md).
+
+For more information on how to use Cosmos, look [here](https://learn.microsoft.com/en-us/azure/cosmos-db/data-explorer).
+
+## Log Analytics Workbook
+
+WebApp logs, Function logs and App Service logs can be found in Log Analytics Workspace.
+
+There exist in this solution a workbook with default queries that can be used to explore and troubleshoot further.
+Check out the section [Workbook Usage](/docs/deployment/worbook_usage.md).
+
+For more information on log analytics and Kusto query language, look [here](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/queries?tabs=groupby).

docs/features/ux_analysispanel.md

@@ -1,6 +1,6 @@
 # Analysis Panel
 
-he Analysis Panel in the UX allows the user to explore three details about the answer to their question:
+The Analysis Panel in the UX allows the user to explore three details about the answer to their question:
 
 * Thought Process
 * Supporting Content
@@ -10,15 +10,23 @@ In this documentation we will cover the specifics of that detail tab.
 
 ## Thought Process
 
-TBD
+The ***Thought Process*** sub-tab of the ***Analysis*** panel displays the entire thought process used throughout the Retrieval Augmented Generation (RAG) process. In the screenshot below, you can see
+
+* Generative AI assisted query terms derived from the users question in orange
+* System Prompt, derived from configured options in the ***Adjust*** panel,in yellow
+* Few shot prompting questions and answer examples in blue
+
+![Analysis Panel Thought Process sub tab view](/docs/images/UX_analysispanel_thoughtprocess.png)
 
 ## Supporting Content
 
-TBD
+The ***Supporting Content*** sub-tab of the ***Analysis*** panel displays the total number of document chunks returned from the Azure AI Search index. The number of chunks returned are driven by settings in the ***Adjust*** panel.
+
+![Analysis Panel Supporting Content sub tab view](/docs/images/UX_analysispanel_supportingcontent.png)
 
 ## Citations
 
-The Citations detail tab includes to sub views. One to display the section of the document ("chunk") that was indexed and returned as a selected result of the search. The second uses metadata from the document section ("chunk") to display the source file and page where the chunk was derived from.
+The ***Citations*** sub-tab of the ***Analysis*** panel includes to sub views itself. One to display a view of the indexed content for the cited section of the document ("chunk"). The second uses metadata from the document section ("chunk") to display the source file and page where the cited chunk originated from.
 
 An example of a "chunk" would be in JSON format like:
 
@@ -40,10 +48,10 @@ An example of a "chunk" would be in JSON format like:
 
 From this content we can derive the file name and pages the "chunk" was derived from using the **file_name** and **pages** attributes.
 
-The "chunk" displays in the **Document Section** tab of the **Citation** tab of the **Analysis Panel**.
+The "chunk" metadata displays in the ***Document Section*** sub view of the ***Citation*** sub-tab of the ***Analysis*** panel.
 
-![Document Section tab of the Citation tab of the Analysis Panel](../images/UX_anlysispanel_citation_documentsection.png)
+![Document Section sub view of the Citation sub tab of the Analysis Panel](../images/UX_anlysispanel_citation_documentsection.png)
 
-The full file displays in the **Document** tab of the **Citation** tab of the **Analysis Panel**.
+The full file displays in the ***Document*** sub view of the ***Citation*** sub-tab of the ***Analysis*** panel.
 
-![Source Document tab of the Citation tab of the Analysis Panel](../images/UX_anlysispanel_citation_document.png)
+![Source Document sub view of the Citation sub tab of the Analysis Panel](../images/UX_anlysispanel_citation_document.png)