diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 6c6e8c71..23d05d5d 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -55,6 +55,9 @@ plugins:
             show_signature_annotations: true
             show_root_heading: true
             members_order: source
+            docstring_section_style: list
+            signature_crossrefs: true
+            separate_signature: true
           import:
             # for cross references
             - https://arrow.apache.org/docs/objects.inv
diff --git a/docs/src/python/python.md b/docs/src/python/python.md
index a9db4060..eba6e1fd 100644
--- a/docs/src/python/python.md
+++ b/docs/src/python/python.md
@@ -1,6 +1,16 @@
 # Python API Reference
 
-This section contains the API reference for the OSS Python API.
+This section contains the API reference for the Python API. There is a
+synchronous and an asynchronous API client.
+
+The general flow of using the API is:
+
+1. Use [lancedb.connect][] or [lancedb.connect_async][] to connect to a database.
+2. Use the returned [lancedb.DBConnection][] or [lancedb.AsyncConnection][] to
+   create or open tables.
+3. Use the returned [lancedb.table.Table][] or [lancedb.AsyncTable][] to query
+   or modify tables.
+
 
 ## Installation