- gently push users towards entity name for simple cases

1 files changed, 13 insertions, 3 deletions

diff --git a/examples/sharding/__init__.py b/examples/sharding/__init__.py
index 19f6db245..d4b463949 100644
--- a/examples/sharding/__init__.py
+++ b/examples/sharding/__init__.py
@@ -1,4 +1,4 @@
-"""a basic example of using the SQLAlchemy Sharding API.
+"""A basic example of using the SQLAlchemy Sharding API.
 Sharding refers to horizontally scaling data across multiple
 databases.
 
@@ -14,7 +14,17 @@ The basic components of a "sharded" mapping are:
   Query ("query_chooser").  If it returns all shard ids, all shards will be 
   queried and the results joined together.
 
-In this example, four sqlite databases will store information about
-weather data on a database-per-continent basis.  We provide example shard_chooser, id_chooser and query_chooser functions.  The query_chooser illustrates inspection of the SQL expression element in order to attempt to determine a single shard being requested.
+In this example, four sqlite databases will store information about weather
+data on a database-per-continent basis. We provide example shard_chooser,
+id_chooser and query_chooser functions. The query_chooser illustrates
+inspection of the SQL expression element in order to attempt to determine a
+single shard being requested.
+
+The construction of generic sharding routines is an ambitious approach
+to the issue of organizing instances among multiple databases.   For a
+more plain-spoken alternative, the "distinct entity" approach 
+is a simple method of assigning objects to different tables (and potentially
+database nodes) in an explicit way - described on the wiki at 
+`EntityName <http://www.sqlalchemy.org/trac/wiki/UsageRecipes/EntityName>`_.
 
 """