diff --git a/doc/config-reference/block-storage/drivers/vmware-vmdk-driver.xml b/doc/config-reference/block-storage/drivers/vmware-vmdk-driver.xml
index 94127167e7..efba185389 100644
--- a/doc/config-reference/block-storage/drivers/vmware-vmdk-driver.xml
+++ b/doc/config-reference/block-storage/drivers/vmware-vmdk-driver.xml
@@ -5,27 +5,25 @@
          xmlns:xlink="http://www.w3.org/1999/xlink"
          version="5.0">
     <title>VMware VMDK driver</title>
-    <para>VMware VMDK driver enables management of cinder volume on VMware
-    vCenter Server or ESX managed datastore. Cinder volume is backed by VMDK
-    files on the datastore.</para>
+    <para>The VMware VMDK driver enables management of OpenStack Block Storage volumes on vCenter
+        managed datastores. Volumes are backed by VMDK files on datastores using any VMware
+        compatible storage technology. (e.g. NFS, iSCSI, FiberChannel, vSAN)</para>
     <simplesect>
         <title>Configuration</title>
-        <para>Two cinder drivers for VMware vCenter server and ESX are
-        provided. Appropriate driver must be configured when using VMware
-        server. For attach/detach operation to an instance, the driver works as
-        expected only with the VMware driver for nova and it does not work
-        with other nova drivers. Both nova and cinder drivers must be
-        configured to the same server. The following table captures the
-        configuration mapping:</para>
+        <para>The recommended OpenStack Block Storage volume driver is the VMware vCenter VMDK
+            driver. An ESX VMDK driver is provided as well, but it has not been extensively tested.
+            When configuring either driver, you must match it with the appropriate OpenStack Compute
+            driver from VMware and both drivers must point to the same server. The following table
+            captures this configuration mapping:</para>
         <table rules="all">
             <caption>
                 Cinder-Nova configuration mapping with VMware server
             </caption>
             <thead>
                 <tr>
-                    <td>VMware server</td>
-                    <td>Nova driver</td>
-                    <td>Cinder driver</td>
+                    <td>VMware Server</td>
+                    <td>OpenStack Compute Driver</td>
+                    <td>OpenStack Block Storage Driver</td>
                 </tr>
             </thead>
             <tbody>
@@ -50,13 +48,12 @@
     </simplesect>
     <simplesect>
         <title>VMDK disk type</title>
-        <para>VMwareVcVmdkDriver and VMwareEsxVmdkDriver support creating
-        VMDK disk file of types: <literal>thin</literal>,
-        <literal>thick</literal> and <literal>eagerZeroedThick</literal>.
-        VMDK disk file type can be specified via volume type extra specs. By
-        using any volume type with appropriate extra spec for volume creation,
-        the driver creates one of the above VMDK disk file type. The following
-        captures extra spec entry to VMDK disk file type mapping:</para>
+        <para>The VMware VMDK drivers support creating VMDK disk files of type:
+                <literal>thin</literal>, <literal>thick</literal> and
+                <literal>eagerZeroedThick</literal>. The VMDK disk file type is specified using the
+                <code>vmware:vmdk_type</code> extra spec key with the appropriate value. The
+            following table captures the mapping between the extra spec entry and the VMDK disk file
+            type:</para>
         <table rules="all">
             <caption>Extra spec entry to VMDK disk file type mapping</caption>
             <thead>
@@ -84,10 +81,10 @@
                 </tr>
             </tbody>
         </table>
-        <para>When no volume type is used or if none of the above extra spec
-        entry is found in the volume type, then the default disk file type
-        used is <literal>thin</literal>.</para>
-        <para>Example: creation of thick VMDK volume</para>
+        <para>If no <code>vmdk_type</code> extra spec entry is specified, the default disk file type is
+                <literal>thin</literal>.</para>
+        <para>The example below shows how to create a <code>thick</code> VMDK volume using the appropriate
+            <code>vmdk_type</code>:</para>
         <screen>
         <prompt>$</prompt> <userinput>cinder type-create thick_volume</userinput>
         <prompt>$</prompt> <userinput>cinder type-key thick_volume set vmware:vmdk_type=thick</userinput>
@@ -96,14 +93,11 @@
     </simplesect>
     <simplesect>
         <title>Clone type</title>
-        <para>VMwareVcVmdkDriver supports clone types: <literal>full</literal>
-        and <literal>linked/fast</literal> while creating volume from another
-        source volume or from a snapshot point. Clone type can be specified via
-        volume type extra specs. By using volume type with appropriate extra
-        spec for creating volume from another source volume or from a snapshot
-        point, the driver creates a <literal>full</literal> clone or a
-        <literal>linked</literal> clone. The following captures extra spec
-        entry to clone type mapping:</para>
+        <para>With the VMware VMDK drivers, you can create a volume from another source volume or
+            from a snapshot point. The VMware vCenter VMDK driver supports clone types
+                <literal>full</literal> and <literal>linked/fast</literal>. The clone type is
+            specified using the <code>vmware:clone_type</code> extra spec key with the appropriate value. The
+            following table captures the mapping for clone types:</para>
         <table rules="all">
             <caption>Extra spec entry to clone type mapping</caption>
             <thead>
@@ -126,30 +120,27 @@
                 </tr>
             </tbody>
         </table>
-        <para>When no volume type is used or if none of the above extra spec
-        entry is found in the volume type, then the default clone type is
-        <literal>full</literal>.</para>
-        <para>Example: linked cloning from another source volume</para>
+        <para>If not specified, the default clone type is <literal>full</literal>.</para>
+        <para>The following is an example of linked cloning from another source volume:</para>
         <screen>
         <prompt>$</prompt> <userinput>cinder type-create fast_clone</userinput>
         <prompt>$</prompt> <userinput>cinder type-key fast_clone set vmware:clone_type=linked</userinput>
         <prompt>$</prompt> <userinput>cinder create --volume-type fast_clone --source-volid 25743b9d-3605-462b-b9eb-71459fe2bb35 --display-name volume1 1</userinput>
         </screen>
-        <para>Note: VMwareEsxVmdkDriver ignores the extra spec entry and always
-        creates a <literal>full</literal> clone while creating volume from
-        another source volume or from a snapshot point.</para>
+        <para>Note: The VMware ESX VMDK driver ignores the extra spec entry and always creates a
+                <literal>full</literal> clone.</para>
     </simplesect>
     <simplesect>
         <title>Supported operations</title>
-        <para>The following operations are supported by VMwareVcVmdkDriver and
-        VMwareEsxVmdkDriver:</para>
+        <para>The following operations are supported by the VMware vCenter and ESX VMDK
+            drivers:</para>
         <itemizedlist>
             <listitem>
                 <para>create volume</para>
             </listitem>
             <listitem>
-                <para>create volume from another source volume: Supported only
-                if source volume is not attached to an instance.</para>
+                <para>create volume from another source volume (Supported only if source volume is
+                    not attached to an instance.)</para>
             </listitem>
             <listitem>
                 <para>create volume from snapshot</para>
@@ -158,35 +149,36 @@
                 <para>create volume from glance image</para>
             </listitem>
             <listitem>
-                <para>attach volume: When a volume is attached to an instance,
-                a reconfigure operation is performed on the instance to add the
-                volume's VMDK to it. The user must manually rescan and mount
-                the device from within the guest operating system.</para>
+                <para>attach volume (When a volume is attached to an instance, a reconfigure
+                    operation is performed on the instance to add the volume's VMDK to it. The user
+                    must manually rescan and mount the device from within the guest operating
+                    system.)</para>
             </listitem>
             <listitem>
                 <para>detach volume</para>
             </listitem>
             <listitem>
-                <para>create snapshot: Allowed only if volume is not attached
-                to an instance.</para>
+                <para>create snapshot (Allowed only if volume is not attached to an
+                    instance.)</para>
             </listitem>
             <listitem>
-                <para>delete snapshot: Allowed only if volume is not attached
-                to an instance.</para>
+                <para>delete snapshot (Allowed only if volume is not attached to an
+                    instance.)</para>
             </listitem>
             <listitem>
-                <para>upload as image to glance: Allowed only if volume is not
-                attached to an instance.</para>
+                <para>upload as image to glance (Allowed only if volume is not attached to an
+                    instance.)</para>
             </listitem>
         </itemizedlist>
+        <para>Note: Although the VMware ESX VMDK driver supports these operations, it has not been
+            extensively tested.</para>
     </simplesect>
     <simplesect>
         <title>Datastore selection</title>
-        <para>The driver chooses datastore that can accommodate for the volume
-        space and has highest <literal>freespace/totalspace</literal> metric
-        value.</para>
-        <para>When the volume is being attached to an instance, the driver
-        tries to place the volume under instance's ESX host on a datastore
-        selected based on the above strategy.</para>
+        <para>When creating a volume, the driver chooses a datastore that has sufficient free space
+            and has the highest <literal>freespace/totalspace</literal> metric value.</para>
+        <para>When a volume is attached to an instance, the driver attempts to place the volume
+            under the instance's ESX host on a datastore that is selected using the strategy
+            above.</para>
     </simplesect>
 </section>