docs: update config docs for GitHub, PagerDuty and SonarQube (#787)

Co-authored-by: Startrekzky <[email protected]>
apache · Sep 20, 2024 · 4bacf10 · 4bacf10
1 parent 6fb221f
commit 4bacf10
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 47 deletions.
diff --git a/docs/Configuration/GitHub.md b/docs/Configuration/GitHub.md
@@ -8,7 +8,7 @@ Visit Config UI at: `http://localhost:4000`.
 
 ## Step 1 - Add Data Connections
 
-On the Connections page, you can select GitHub and create a new connection on it.
+On the **Connections** page, you can select GitHub and create a new connection on it.
 
 ### Step 1.1 - Authentication
 ![github-add-data-connections](images/github-create-a-connection.png)
@@ -105,9 +105,9 @@ Click `Test Connection`, if the connection is successful, click `Save Connection
 
 ### Step 1.2 - Add Data Scopes
 
-#### Repositories
+Choose the GitHub repositories you wish to collect either by finding them in the miller column, or searching. 
 
-Choose the GitHub repositories you wish to collect either by finding them in the miller column, or searching. You can only add public repositories through the search box.
+You can only add public repositories through the search box.
 
 
 ![github-set-data-scope](images/github-add-data-scopes.png)
@@ -193,17 +193,20 @@ Please click `Save` to save the transformation rules for the repo. In the data s
 
 ## Step 2 - Collect Data in a Project
 ### Step 2.1 - Create a Project
-Collecting GitHub data requires creating a project first. You can visit the Project page from the side menu and create a new project by following the instructions on the user interface.
+Collecting GitHub data requires creating a project first. 
+
+Navigate to the **Projects** page from the side menu and create a new project.
 
 ![create-a-project](images/create-a-project.png)
 
 ### Step 2.2 - Add a GitHub Connection
-You can add a previously configured GitHub connection to the project and select the boards for which you wish to collect the data for.
+Add the GitHub connection to the project and select the repos you wish to sync in this project.
+
 Please note: if you don't see the repositories you are looking for, please check if you have added them to the connection first.
 
 ![add-a-connection](images/add-a-connection-project.png)
 
-### Step 2.3 - Set the Sync Policy
+### Step 2.3 - Set the Sync Policy (Optional)
 There are three settings for Sync Policy:
 - Data Time Range: You can select the time range of the data you wish to collect. The default is set to the past six months.
 - Sync Frequency: You can choose how often you would like to sync your data in this step by selecting a sync frequency option or enter a cron code to specify your preferred schedule.
@@ -212,7 +215,10 @@ There are three settings for Sync Policy:
 ![sync-policy](images/sync-policy.png)
 
 ### Step 2.4 - Start Data Collection
-Click on "Collect Data" to start collecting data for the whole project. You can check the status in the Status tab on the same page.
+Click on **Collect Data** to start collecting data for the whole project, including the SonarQube data. 
+
+You can also trigger the data sync at the **General Settings/Status** page (The previous **Blueprint/Status** page).
+
 ![collect-data](images/collect-data.png)
 
 

diff --git a/docs/Configuration/PagerDuty.md b/docs/Configuration/PagerDuty.md
@@ -8,49 +8,50 @@ Visit Config UI at: `http://localhost:4000`.
 
 ## Step 1 - Add Data Connections
 
+### Step 1.1 - Authentication
 ![pagerduty-create-a-connection](images/pagerduty-create-a-connection.png)
 
-### Connection Name
+#### Connection Name
 
 Give your connection a unique name to help you identify it in the future.
 
-### Token
+#### Token
 
 Paste your PagerDuty personal access token (PAT) here. You may make it a Read-Only token for the plugin's purposes.
 
-### Test and Save Connection
+#### Test and Save Connection
 
 Click `Test Connection`, if the connection is successful, click `Save Connection` to add the connection.
 
-## Step 1 - Add Data Connection
+### Step 1.2 - Add Data Scopes
 
-Create a project for PagerDuty by adding the connection created above to it.
+Choose the **PagerDuty services** to collect.
 
-![pagerduty-add-data-connection](images/pagerduty-add-data-connection.png)
+Only PagerDuty incidents will be collected. The data will be stored in table issues and incidents.
 
-## Step 2 - Setting Data Scope
+Note: PagerDuty plugin does not support any scope config.
 
-### Select services
+## Step 2 - Collect PagerDuty Data in a Project
+### Step 2.1 - Create a Project
+Collecting PagerDuty data requires creating a project first. 
 
-Select the services you want to collect data from.
+Navigate to the **Projects** page from the side menu and create a new project.
 
-![pagerduty-set-data-scope](images/pagerduty-set-data-scope.png)
+### Step 2.2 - Add a PagerDuty Connection
+Create a project, add the PagerDuty connection.
 
-### Data Entities
+Please note: if you don't see the repositories you are looking for, please check if you have added them to the connection first.
 
-PagerDuty supports the following data entities.
+### Step 2.3 - Set the Sync Policy (Optional)
+There are three settings for Sync Policy:
+- Data Time Range: You can select the time range of the data you wish to collect. The default is set to the past six months.
+- Sync Frequency: You can choose how often you would like to sync your data in this step by selecting a sync frequency option or enter a cron code to specify your preferred schedule.
+- Skip Failed Tasks: sometime a few tasks may fail in a long pipeline; you can choose to skip them to avoid spending more time in running the pipeline all over again.
 
-- Issue Tracking: These map to PagerDuty incidents.
+### Step 2.4 - Start Data Collection
+Click on **Collect Data** to start collecting data for the whole project, including the SonarQube data. 
 
-## Step 3 - Adding Transformation Rules (Optional)
-
-Currently, this plugin does not support transformation rules, so skip this page by clicking `Next Step`.
-
-## Step 4 - Set Sync Policy
-
-Set the sync policy as you see fit. Note that PagerDuty can only collect data from up to 6 months prior to the present time.
-
-![pagerduty-sync-policy](images/pagerduty-sync-policy.png)
+You can also trigger the data sync at the **General Settings/Status** page (The previous **Blueprint/Status** page).
 
 ## Troubleshooting
 

diff --git a/docs/Configuration/SonarQube.md b/docs/Configuration/SonarQube.md
@@ -8,57 +8,71 @@ Visit Config UI at: `http://localhost:4000`.
 
 ## Step 1 - Add Data Connections
 
+### Step 1.1 - Authentication
 ![sonarqube-add-data-connections](/img/ConfigUI/sonarqube-add-data-connections.png)
 
-### Connection Name
+#### Connection Name
 
 Name your connection.
 
-### Endpoint URL
+#### Endpoint URL
 
 This should be a valid REST API endpoint
 
 - `http://<host>:<port>/api/`
 
 The endpoint url should end with `/`.
 
-### Token
+#### Token
 
 Please use a system admin account to create the SonarQube token, because some SonarQube APIs require this permission to list all projects. Learn about [how to create a SonarQube token](https://docs.sonarsource.com/sonarqube/8.9/user-guide/user-account/generating-and-using-tokens/#generating-a-token).
 
-### Proxy URL (Optional)
+#### Proxy URL (Optional)
 
 If you are behind a corporate firewall or VPN you may need to utilize a proxy server. Enter a valid proxy server address on your network, e.g. `http://your-proxy-server.com:1080`
 
-### Fixed Rate Limit (Optional)
+#### Fixed Rate Limit (Optional)
 
 DevLake uses a dynamic rate limit at around 18,000 requests/hour to collect SonarQube data. You can adjust the rate limit if you want to increase or lower the speed.
 
-### Test and Save Connection
+#### Test and Save Connection
 
 Click `Test Connection`, if the connection is successful, click `Save Connection` to add the connection.
 
-## Step 2 - Setting Data Scope
+### Step 1.2 - Add Data Scopes
 
-![sonarqube-set-data-scope](/img/ConfigUI/sonarqube-set-data-scope.png)
+Choose the **SonarQube projects** to collect. The following data entities in the selected projects will be collected:
+- Code Quality Domain: SonarQube issues, issue code blocks, file metrics, hotspots, etc.
+- Cross Domain: SonarQube accounts, etc.
 
-### Projects
+Note: SonarQube plugin does not support any scope config.
 
-Choose the SonarQube projects to collect.
+## Step 2 - Collect SonarQube Data in a Project
+### Step 2.1 - Create a Project
+Collecting SonarQube data requires creating a project first. 
 
-### Data Entities
+Navigate to the Project page from the side menu and create a new project.
 
-Usually, you don't have to modify this part. However, if you don't want to collect certain SonarQube entities, you can unselect some entities to accerlerate the collection speed.
+![create-a-project](images/create-a-project.png)
 
-- Code Quality Domain: SonarQube issues, issue code blocks, file metrics, hotspots, etc.
-- Cross Domain: SonarQube accounts, etc.
+### Step 2.2 - Add a SonarQube Connection
+You can add a previously configured SonarQube connection to the project and select the projects you wish to collect data from.
+
+Please note: if you don't see the repositories you are looking for, please check if you have added them to the connection first.
+
+### Step 2.3 - Set the Sync Policy
+There are two settings for Sync Policy:
+- Sync Frequency: You can choose how often you would like to sync your data in this step by selecting a sync frequency option or enter a cron code to specify your preferred schedule.
+- Skip Failed Tasks: sometime a few tasks may fail in a long pipeline; you can choose to skip them to avoid spending more time in running the pipeline all over again.
+
+Please note that the 'Data Time Range' setting will not affect the SonarQube data to collect, as the SonarQube plugin will only collect the issues and metrics of the latest Sonar scan results.
 
-## Step 3 - Adding Transformation Rules (Optional)
-SonarQube does not have transformation and this step will be skipped.
+![sync-policy](images/sync-policy.png)
 
-## Step 4 - Setting Sync Policy
+### Step 2.4 - Start Data Collection
+Click on **Collect Data** to start collecting data for the whole project, including the SonarQube data. 
 
-You can choose how often you would like to sync your data in this step by selecting a sync frequency option or enter a cron code to specify your prefered schedule.
+You can also trigger the data sync at the **General Settings/Status** page (the previous **Blueprint/Status** page).
 
 ## Troubleshooting