added motivation to docs

README.md

@@ -36,7 +36,7 @@ When switching to parallel execution of tests, even more difficulties arise:
   - restricting user privileges to prevent schema modification by rogue tests
   - dropping temporary databases before or after a test run to reduce clutter
 
-`db-pool` takes care of all of these concerns while supporting multiple DBMSes, backends, and connection pools.
+`db-pool` takes care of all of these concerns while supporting multiple database types, backends, and connection pools.
 
 ## Databases
 

book/src/README.md

@@ -26,7 +26,7 @@ When switching to parallel execution of tests, even more difficulties arise:
   - restricting user privileges to prevent schema modification by rogue tests
   - dropping temporary databases before or after a test run to reduce clutter
 
-`db-pool` takes care of all of these concerns while supporting multiple DBMSes, backends, and connection pools.
+`db-pool` takes care of all of these concerns while supporting multiple database types, backends, and connection pools.
 
 ## Databases
 

src/lib.rs

@@ -6,14 +6,38 @@
 //! - Automatic creation, reuse, and cleanup
 //! - Async support
 //!
+//! ## Motivation
+//!
+//! When running tests against a database-tied service, such as a web server, a test database is generally used. However, this comes with its own set of difficulties:
+//!
+//! 1) The database has to be either (a) dropped and re-created or (b) cleaned before every test.
+//! 2) Tests have to run serially in order to avoid cross-contamination.
+//!
+//! This leads to several issues when running tests serially:
+//!
+//! - Test setup and teardown is now required.
+//! - Dropping and creating a database from scratch can be expensive.
+//! - Cleaning a database instead of dropping and re-creating one requires careful execution of dialect-specific statements.
+//!
+//! When switching to parallel execution of tests, even more difficulties arise:
+//!
+//! - Creating and dropping a database for each test can be expensive.
+//! - Sharing temporary databases across tests requires:
+//!   - isolating databases in concurrent use
+//!   - cleaning each database before reuse by a subsequent test
+//!   - restricting user privileges to prevent schema modification by rogue tests
+//!   - dropping temporary databases before or after a test run to reduce clutter
+//!
+//! `db-pool` takes care of all of these concerns while supporting multiple database types, backends, and connection pools.
+//!
 //! ### Databases
 //!
 //! - MySQL (MariaDB)
 //! - PostgreSQL
 //!
-//! ### Backends & Pools
+//! ## Backends & Pools
 //!
-//! #### Sync
+//! ### Sync
 //!
 //! | Backend                                               | Pool                                      | Feature           |
 //! | ----------------------------------------------------- | ----------------------------------------- | ----------------- |
@@ -22,7 +46,7 @@
 //! | [mysql](struct@sync::MySQLBackend)                    | [r2d2](https://docs.rs/r2d2/0.8.10/r2d2/) | `mysql`           |
 //! | [postgres](struct@sync::PostgresBackend)              | [r2d2](https://docs.rs/r2d2/0.8.10/r2d2/) | `postgres`        |
 //!
-//! #### Async
+//! ### Async
 //!
 //! | Backend                                                           | Pool                                                                                      | Features                                    |
 //! | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------- |