update user guide to position spark.ml better (SPARK-5254)

2 files changed, 21 insertions, 16 deletions

diff --git a/site/docs/1.2.0/ml-guide.html b/site/docs/1.2.0/ml-guide.html
index d865c263c..654809e93 100644
--- a/site/docs/1.2.0/ml-guide.html
+++ b/site/docs/1.2.0/ml-guide.html
@@ -123,15 +123,16 @@
             <h1 class="title">Spark ML Programming Guide</h1>
           
 
-          <p>Spark ML is Spark&#8217;s new machine learning package.  It is currently an alpha component but is potentially a successor to <a href="mllib-guide.html">MLlib</a>. The <code>spark.ml</code> package aims to replace the old APIs with a cleaner, more uniform set of APIs which will help users create full machine learning pipelines.</p>
-
-<p>MLlib vs. Spark ML:</p>
-
-<ul>
-  <li>Users can use algorithms from either of the two packages, but APIs may differ.  Currently, <code>spark.ml</code> offers a subset of the algorithms from <code>spark.mllib</code>. Since Spark ML is an alpha component, its API may change in future releases.</li>
-  <li>Developers should contribute new algorithms to <code>spark.mllib</code> and can optionally contribute to <code>spark.ml</code>.  See below for more details.</li>
-  <li>Spark ML only has Scala and Java APIs, whereas MLlib also has a Python API.</li>
-</ul>
+          <p><code>spark.ml</code> is a new package introduced in Spark 1.2, which aims to provide a uniform set of
+high-level APIs that help users create and tune practical machine learning pipelines.
+It is currently an alpha component, and we would like to hear back from the community about
+how it fits real-world use cases and how it could be improved.</p>
+
+<p>Note that we will keep supporting and adding features to <code>spark.mllib</code> along with the
+development of <code>spark.ml</code>.
+Users should be comfortable using <code>spark.mllib</code> features and expect more features coming.
+Developers should contribute new algorithms to <code>spark.mllib</code> and can optionally contribute
+to <code>spark.ml</code>.</p>
 
 <p><strong>Table of Contents</strong></p>
 
diff --git a/site/docs/1.2.0/mllib-guide.html b/site/docs/1.2.0/mllib-guide.html
index 573d22ed2..fdee3fd75 100644
--- a/site/docs/1.2.0/mllib-guide.html
+++ b/site/docs/1.2.0/mllib-guide.html
@@ -175,16 +175,20 @@ filtering, dimensionality reduction, as well as underlying optimization primitiv
 The APIs marked <code>Experimental</code>/<code>DeveloperApi</code> may change in future releases, 
 and the migration guide below will explain all changes between releases.</p>
 
-<h1 id="sparkml-the-new-ml-package">spark.ml: The New ML Package</h1>
+<h1 id="sparkml-high-level-apis-for-ml-pipelines">spark.ml: high-level APIs for ML pipelines</h1>
 
-<p>Spark 1.2 includes a new machine learning package called <code>spark.ml</code>, currently an alpha component but potentially a successor to <code>spark.mllib</code>.  The <code>spark.ml</code> package aims to replace the old APIs with a cleaner, more uniform set of APIs which will help users create full machine learning pipelines.</p>
+<p>Spark 1.2 includes a new package called <code>spark.ml</code>, which aims to provide a uniform set of
+high-level APIs that help users create and tune practical machine learning pipelines.
+It is currently an alpha component, and we would like to hear back from the community about
+how it fits real-world use cases and how it could be improved.</p>
 
-<p>See the <strong><a href="ml-guide.html">spark.ml programming guide</a></strong> for more information on this package.</p>
-
-<p>Users can use algorithms from either of the two packages, but APIs may differ.  Currently, <code>spark.ml</code> offers a subset of the algorithms from <code>spark.mllib</code>.</p>
+<p>Note that we will keep supporting and adding features to <code>spark.mllib</code> along with the
+development of <code>spark.ml</code>.
+Users should be comfortable using <code>spark.mllib</code> features and expect more features coming.
+Developers should contribute new algorithms to <code>spark.mllib</code> and can optionally contribute
+to <code>spark.ml</code>.</p>
 
-<p>Developers should contribute new algorithms to <code>spark.mllib</code> and can optionally contribute to <code>spark.ml</code>.
-See the <code>spark.ml</code> programming guide linked above for more details.</p>
+<p>See the <strong><a href="ml-guide.html">spark.ml programming guide</a></strong> for more information on this package.</p>
 
 <h1 id="dependencies">Dependencies</h1>