Clarify in reference documentation that the callback-based async driver is deprecated

JAVA-3217

Author: jyemin

docs/landing/layouts/partials/features.html

@@ -8,7 +8,7 @@ <h2>Features</h2>
   <dt>MongoDB Driver</dt>
   <dd>An updated Java driver that includes the legacy API as well as a new generic MongoCollection interface that complies with a new cross-driver CRUD specification.</dd>
   <dt>MongoDB Async Driver</dt>
-  <dd>A new asynchronous API that can leverage either Netty or Java 7's AsynchronousSocketChannel for fast and non-blocking IO.</dd>
-  <dt>Core driver</dt>
-  <dd>The MongoDB Driver and Async Driver are both built on top of a new core library, which anyone can use to build alternative or experimental high-level APIs.</dd>
+  <dd>A callback-based asynchronous driver.  Note that this driver is now deprecated in favor of the
+      <a href="http://mongodb.github.io/mongo-java-driver-reactivestreams/">Reactive Streams Java Driver</a>
+  </dd>
 </dl>

docs/landing/layouts/partials/introduction.html

@@ -2,5 +2,4 @@ <h2>Introduction</h2>
 
 <p>
   The official MongoDB Java Driver providing both synchronous and asynchronous interaction with MongoDB.
-  Powering the drivers is a new driver core and BSON library.
 </p>

docs/reference/content/index.md

@@ -23,7 +23,9 @@ For the synchronous MongoDB Driver, see [MongoDB Driver section]({{< relref "dri
 
 ### MongoDB Async Driver
 
-For the new asynchronous MongoDB Async Driver, the [MongoDB Async Driver section]({{< relref "driver-async/index.md" >}}).
+For the callback-based asynchronous MongoDB Async Driver, see [MongoDB Async Driver section]({{< relref "driver-async/index.md" >}}). Note 
+that this driver has been deprecated in favor of the 
+[Reactive Streams Java Driver](http://mongodb.github.io/mongo-java-driver-reactivestreams/). 
 
 ### BSON Library
 

docs/reference/content/upgrading.md

@@ -9,8 +9,17 @@ title = "Upgrade Considerations"
 
 ## Upgrading from 3.9.x
 
+Please note that two large portions of the current driver have been deprecated as of the 3.9.0 release:
+
+* The callback-based asynchronous driver has been deprecated in favor of the 
+[Reactive Streams Java Driver](http://mongodb.github.io/mongo-java-driver-reactivestreams/).
+* Much of the "core" driver on which the both the asynchronous and synchronous drivers are built has been deprecated.  In 3.0 we made most
+of this "core" driver a public API, but the benefit to users has turned out to be small and the maintenance costs of maintaining backwards 
+compatibility has turned out to be high.  For that reason we've decided to remove it from the public API (though it will still continue 
+to exist as an implementation artifact).
+
 In the upcoming 4.0 release, all deprecated API elements except those documented as "not currently scheduled for removal" will be removed. 
-Currently the only API elements _not_ scheduled for removal are:
+Currently the only deprecated API elements _not_ scheduled for removal are:
 
 * [`Mongo.getDB`]({{<apiref "com/mongodb/Mongo.html#getDB-java.lang.String-">}})
 * [`JsonMode.STRICT`]({{<apiref "org/bson/json/JsonMode.html#STRICT">}})