Apply suggestions from code review

Co-authored-by: Leon Kuchenbecker <[email protected]>

user_docs/connector/connector.md

@@ -1,38 +1,20 @@
 # GHGA Connector
 
-The GHGA Connector is a Python library and command line facilitating interaction with the file storage infrastructure of GHGA. Currently, it provides functionality for downloading and decrypting files, with the capability to interact with the RESTful APIs exposed by the Download Controller Service (https://github.com/ghga-de/download-controller-service).
+The GHGA Connector is a command line tool and Python library facilitating interaction with the file storage infrastructure of GHGA. Currently, it provides functionality for downloading and decrypting files.
 
 
 ## Installation and Upgrade
 
-We recommend installing the latest version of the GHGA connector using pip.
+We recommend installing / upgrading to the latest version of the GHGA connector using pip.
 
-Install:
-```
-pip install ghga-connector==0.3.15
-```
-
-Upgrade:
-```
-pip install --upgrade ghga-connector
-```
-
-:warning: Please note that the installation instructions currently require you install a specific version of the GHGA Connector rather than the latest available version. This is due to a current change in how we manage package versions and dependencies. This will be resolved soon and this documentation will be updated.
+Install or upgrade:
+    pip install --upgrade ghga-connector
 
 
-## Configuration
-
-GHGA Connector requires a connection to the backend service API. Please set the following environment variable correctly in your shell before using the CLI.
-
-```bash
-export ghga_connector_wkvs_api_url="https://<CHANGE-HERE>" 
-```
-
-For further details about configuration, please visit the [GHGA Connector](https://github.com/ghga-de/ghga-connector) GitHub page.
 
 ### Crypt4gh Keys
 
-GHGA Connector requires your [Crypt4GH](https://crypt4gh.readthedocs.io/en/latest/) keys to encrypt downloaded data, ensuring that only you can access it. Please create a pair of Crypt4GH keys if you don't already have one, which you will also need for the process of download token creation.
+GHGA Connector requires a [Crypt4GH](https://crypt4gh.readthedocs.io/en/latest/) key pair to download data. Please create a pair of Crypt4GH keys if you don't already have one. The public key is also needed for the creation of the download token through the Data Portal.
 
 By default, GHGA Connector looks for the keys at ./key.pub and ./key.sec. You can either place your keys there or use CLI options to specify your key locations.
 
@@ -61,19 +43,19 @@ The _`download`_ command is used to download files. In order to download files,
 
 ### Download Token
 
-GHGA Connector requires a download token to authenticate and process your request against GHGA Central. Each download request is represented by a download token, which should be created via the GHGA Data Portal. For further information on how to create a download token, please read the [Data Access and Download](../download/download.md) document.
+GHGA Connector requires a download token to authenticate and process your request against GHGA Central. Each download request - which may comprise multiple files - is represented by a download token, which should be created via the GHGA Data Portal. For further information on how to create a download token, please read the [Data Access and Download](../download/download.md) document.
 
 ### Download Examples
 
 1. To download a dataset:
 ```bash
 ghga-connector download --output-dir <OUTPUT-DIR>
 ```
-Command will prompt:
+You will then be asked to provide the download token:
 ```
 Please paste the complete download token that you copied from the GHGA data portal: 
 ```
-Paste the *download token* you created via the GHGA data portal, and download process will be initiated.
+Paste the *download token* you created via the GHGA data portal and the download process will be initiated.
 
 Download command usage:
 ```

user_docs/download/download.md

@@ -1,33 +1,33 @@
 # Access Data and Download
 
-## Getting access to data
+## Requesting access to a dataset
 
 The GHGA Data Portal enables users to request access to data through the portal. Browse for your dataset of interest and then click on the "Request Access" button. This will direct you to a data access request form. Complete the form with the necessary information and submit it to request access to the dataset. The data access committee will review your request and respond accordingly.
 
 For further details on how to access data, please read the instructions on the [GHGA Data Portal](https://data.staging.ghga.dev/download).
 
 ## Create a download token
 
-After a user has been granted access to a dataset of interest, the user utilizes the CLI tool GHGA Connector to perform the download. In order to do this users have to create a download token to authenticate and process the request against GHGA Central. Each download request is represented by a download token, which can be created via the GHGA Data Portal.
+After a user has been granted access to a dataset, the user initiates a data download by creating a download token in the Data Portal. A single download token can be generated to download either a single or multiple files from a dataset. The download token is then passed on to the CLI tool GHGA Connector to perform the actual download.
 
 1. Navigate to the [GHGA Data Portal](https://data.staging.ghga.dev/download).
 
-2. Visit your profile page to see the datasets you have access.
+2. Visit your profile page to see the datasets you have access to.
 
     ![Dataset access link](../assets/img/dataset-link.png){ width="500" }
 
 3. Navigate to the dataset list and select your dataset of interest to be downloaded.
 
     ![Select dataset](../assets/img/dataset-select.png){ width="500" }
 
-4. Fill the form with necessary information in order to create a download token.
+4. Fill the form with the necessary information in order to create a download token. Specifying one or multiple file IDs is optional, if not information is provided the entire dataset will be downloaded. A Crypt4GH keypair must be created and the public key must be provided before submitting the form.
 
     ![Token form](../assets/img/token-form.png){ width="500" }
 
 
 ### Crypt4gh Keys
 
-Download process requires your [Crypt4GH](https://crypt4gh.readthedocs.io/en/latest/) keys to encrypt downloaded data, ensuring that only you can access it. Please create a pair of Crypt4GH keys if you don't already have one.
+The download process requires your [Crypt4GH](https://crypt4gh.readthedocs.io/en/latest/) key pair to decrypt the download token. You must specify the key pair corresponding to the public key that was used when the download token was created.
 
 Please paste your *public* Crypt4GH key to the related input box during the token creation.