Improve README.md

Author: gabotechs

README.md

@@ -8,8 +8,8 @@ Library that brings distributed execution capabilities to [DataFusion](https://g
 ## What can you do with this crate?
 
 This crate is a toolkit that extends [DataFusion](https://github.com/apache/datafusion) with distributed capabilities,
-providing a developer experience as close as possible to vanilla DataFusion and being opinionated about the networking
-stack used for hosting the different workers involved in a query.
+providing a developer experience as close as possible to vanilla DataFusion while being unopinionated about the
+networking stack used for hosting the different workers involved in a query.
 
 Users of this library can expect to take their existing single-node DataFusion-based systems and add distributed
 capabilities with minimal changes.
@@ -18,16 +18,16 @@ capabilities with minimal changes.
 
 - Be as close as possible to vanilla DataFusion, providing a seamless integration with existing DataFusion systems and
   a familiar API for building applications.
-- Unopinionated networking. This crate does not take any opinion about the networking stack, and users are expected
-  to leverage their own infrastructure for hosting DataFusion nodes.
+- Unopinionated about networking. This crate does not take any opinion about the networking stack, and users are
+  expected to leverage their own infrastructure for hosting DataFusion nodes.
 - No coordinator-worker architecture. To keep infrastructure simple, any node can act as a coordinator or a worker.
 
 ## Architecture
 
 A distributed DataFusion query is executed in a very similar fashion as a normal DataFusion query with one key
 difference:
 
-The physical plan is divided into stages that can be executed in different machines, and exchange data using Arrow
+The physical plan is divided into stages that can be executed on different machines and exchange data using Arrow
 Flight. All of this is done at the physical plan level, and is implemented as a `PhysicalOptimizerRule` that:
 
 1. Inspects the non-distributed plan, placing network boundaries (`ArrowFlightReadExec` nodes) in the appropriate places
@@ -111,7 +111,8 @@ shows the partitioning scheme in each node):
    └──────[0][1][2]───────┘  
 ```
 
-Based on that boundary, the plan is divided into stages and tasks are assigned to each stage:
+Based on that boundary, the plan is divided into stages and tasks are assigned to each stage. Each task will be
+responsible for the different partitions in the original plan.
 
 ```                            
                               ┌────── (stage 2) ───────┐
@@ -150,9 +151,30 @@ This means that:
 2. Upon calling `.execute()` on the `ArrowFlightReadExec`, instead of recursively calling `.execute()` on its children,
    they will be serialized and sent over the wire to another node.
 3. The next node, which is hosting an Arrow Flight Endpoint listening for gRPC requests over an HTTP server, will pick
-   up the request containing the serialized chunk of the overall plan, and execute it.
+   up the request containing the serialized chunk of the overall plan and execute it.
 4. This is repeated for each stage, and data will start flowing from bottom to top until it reaches the head stage.
 
+## Getting familiar with distributed DataFusion
+
+There are some runnable examples showcasing how to provide a localhost implementation for Distributed DataFusion in
+[examples/](examples):
+
+- [localhost_worker.rs](examples/localhost_worker.rs): code that spawns an Arrow Flight Endpoint listening for physical
+  plans over the network.
+- [localhost_run.rs](examples/localhost_run.rs): code that distributes a query across the spawned Arrow Flight Endpoints
+  and executes it.
+
+The integration tests also provide an idea about how to use the library and what can be achieved with it:
+
+- [tpch_validation_test.rs](tests/tpch_validation_test.rs): executes all TPCH queries and performs assertions over the
+  distributed plans.
+- [custom_config_extension.rs](tests/custom_config_extension.rs): showcases how to propagate custom DataFusion config
+  extensions.
+- [custom_extension_codec.rs](tests/custom_extension_codec.rs): showcases how to propagate custom physical extension
+  codecs.
+- [distributed_aggregation.rs](tests/distributed_aggregation.rs): showcases how to manually place `ArrowFlightReadExec`
+  nodes in a plan and build a distributed query out of it.
+
 ## Development
 
 ### Prerequisites