Fleshing things out a bit.

docs/index.md

@@ -18,40 +18,50 @@ that client to
 * request the transfer of one or more of these data files between databases by
   using canonical file IDs
 
+## Prerequisites for Using `dtspy`
+
+To use the DTS Python client, you need
+
+* Python 3.12
+* an [ORCID account](https://orcid.org/register)
+* a [KBase developer account](https://docs.kbase.us/development/create-a-kbase-developer-account) with a
+  [developer token](https://kbase.github.io/kb_sdk_docs/tutorial/3_initialize.html#set-up-your-developer-credentials)
+
+DTS uses KBase's authentication server, so the token associates your DTS client
+with your KBase account, allowing you to transfer files to it.
+
 ## Installation
 
-`dtspy` requires Python 3.12 or greater. We recommend installing it in a
-[virtual environment](https://docs.python.org/3/library/venv.html) alongside any
-tools or workflows you use to analyze the data you're searching for and
-transferring. You can install `dtspy` using `pip` (or `pip3`):
+We recommend installing `dtspy` in a [virtual environment](https://docs.python.org/3/library/venv.html)
+alongside any tools or workflows you use to analyze the data you're working with.
+You can install `dtspy` using `pip` (or `pip3`):
 
 ```
 pip install dtspy
 ```
 
-The DTS uses KBase's authentication server, so you also need a
-[KBase developer account](https://docs.kbase.us/development/create-a-kbase-developer-account)
-with a [credential (token)](https://kbase.github.io/kb_sdk_docs/tutorial/3_initialize.html#set-up-your-developer-credentials).
-
-To avoid putting your developer token in your Python scripts, you can store it
-in an environment variable like `DTS_KBASE_DEV_TOKEN`. We'll use this environment
-variable to access your token in the examples below.
-
 ## Quickstart
 
-Here's an example how you can create a DTS client connected to a server,
-search for files within the JGI Data Portal, and print their metadata:
+Below is an example describing how to create a DTS client connected to a server,
+search for files within the JGI Data Portal, and print their metadata.
+
 
 ```
 import dts
 import os
 
+# to avoid putting your developer token in your Python scripts, store it
+# in an environment variable like `DTS_KBASE_DEV_TOKEN`
 token = os.getenv('DTS_KBASE_DEV_TOKEN')
+
+# connect to the DTS server
 dts_client = dts.Client(api_key = token,
                         server = "https://lb-dts.staging.kbase.us")
 
-results = dts_client.search(database = 'jdp',
-                            query = 'prochlorococcus')
-print(results)
+# search the JGI Data Portal for files related to prochlorococcus, a small
+# marine cyanobacteria
+files = dts_client.search(database = 'jdp',
+                          query = 'prochlorococcus')
+print(files)
 
 ```