Documentation: Improve conciseness and wording of recently updated se…

…ctions

Co-authored-by: Mathias Fußenegger <[email protected]>

docs/by-example/connection.rst

@@ -5,9 +5,9 @@ The Connection object
 This documentation section outlines different attributes, methods, and
 behaviors of the ``crate.client.connection.Connection`` object.
 
-To improve focus and reduce boilerplate, the example code uses an instance of
-``ClientMocked`` instead of a real ``Client`` instance. It is used for
-demonstration purposes, so the example doesn't need a real database connection.
+The examples use an instance of ``ClientMocked`` instead of a real ``Client``
+instance. This allows us to verify the examples without needing a real database
+connection.
 
 .. rubric:: Table of Contents
 

docs/by-example/cursor.rst

@@ -5,9 +5,8 @@ The Cursor object
 This documentation section outlines different attributes, methods, and
 behaviors of the ``crate.client.cursor.Cursor`` object.
 
-To improve focus and reduce boilerplate, the example code uses both
-``ClientMocked`` and ``set_next_response``. They are required for demonstration
-purposes, so the example does not need a real database connection.
+The example code uses ``ClientMocked`` and ``set_next_response`` for
+demonstration purposes, so they don't need a real database connection.
 
 .. rubric:: Table of Contents
 

docs/by-example/index.rst

@@ -8,15 +8,15 @@ About
 *****
 
 This part of the documentation contains examples how to use the CrateDB Python
-client, exercising different options and scenarios.
+client.
 
 
 DBAPI, HTTP, and BLOB interfaces
 ================================
 
 The examples in this section are all about CrateDB's `Python DBAPI`_ interface,
 the plain HTTP API interface, and a convenience interface for working with
-`blob tables`_. It also details attributes, methods, and behaviors of the
+`blob tables`_. It details attributes, methods, and behaviors of the
 ``Connection`` and ``Cursor`` objects.
 
 .. toctree::

docs/by-example/sqlalchemy/crud.rst

@@ -2,12 +2,14 @@
 SQLAlchemy: Create, retrieve, update, and delete
 ================================================
 
-This section of the documentation, related to CrateDB's SQLAlchemy integration,
-focuses on showing specific details when querying, inserting, updating, and
-deleting records.
+This section of the documentation shows how to query, insert, update and delete
+data using CrateDB's SQLAlchemy integration, it includes common scenarios like:
 
-It exercises filtering and limiting, inserting and updating with default values,
-and updating complex data types with nested Python dictionaries.
+
+- Filtering records
+- Limiting result sets
+- Inserts and updates with default values
+- Updating complex data types with nested dictionaries
 
 .. rubric:: Table of Contents
 

docs/by-example/sqlalchemy/inspection-reflection.rst

@@ -2,23 +2,23 @@
 SQLAlchemy: Database schema inspection and reflection
 =====================================================
 
-This section of the documentation, related to CrateDB's SQLAlchemy integration,
-focuses on database schema inspection and reflection features. That is, given
-that you connect to an existing database, how to introspect its metadata
-information to retrieve table- and view-names, and table column metadata.
+This section shows you how to inspect the schema of a database using CrateDB's
+SQLAlchemy integration.
 
 
 Introduction
 ============
 
-The `runtime inspection API`_ provides the ``inspect()`` function, which
-delivers runtime information about a wide variety of SQLAlchemy objects, both
-within SQLAlchemy Core and the SQLAlchemy ORM.
 
-The ``CrateDialect`` instance provides metadata about the CrateDB cluster,
-like version and schema information.
+The CrateDB SQLAlchemy integration provides different ways to inspect the database.
 
-As always, let's start with creating an ``Engine`` instance.
+1) The `runtime inspection API`_ allows you to get an ``Inspector`` instance that can be used to fetch schema names, table names and other information.
+
+2) Reflection capabilities allow you to create ``Table`` instances from existing tables to inspect their columns and constraints.
+
+3) A ``CrateDialect`` allows you to get connection information and it contains low level function to check the existence of schemas and tables.
+
+All approaches require an ``Engine`` instance, which you can create like this:
 
     >>> import sqlalchemy as sa
     >>> engine = sa.create_engine(f"crate://{crate_host}")
@@ -29,7 +29,8 @@ Inspector
 
 The `SQLAlchemy inspector`_ is a low level interface which provides a
 backend-agnostic system of loading lists of schema, table, column, and
-constraint descriptions from a given database.
+constraint descriptions from a given database. You create an inspector like
+this:
 
     >>> inspector = sa.inspect(engine)
 
@@ -60,9 +61,9 @@ Get default schema name:
 Schema-supported reflection
 ===========================
 
-A ``Table`` object can be instructed to load information about itself from the
-corresponding database schema object already existing within the database. This
-process is called *reflection*, see `reflecting database objects`_.
+A ``Table`` object can load its own schema information from the corresponding
+table in the database. This process is called *reflection*, see `reflecting
+database objects`_.
 
 In the most simple case you need only specify the table name, a ``MetaData``
 object, and the ``autoload_with`` argument.