Index: libcxx/docs/DesignDocs/ABIVersioning.rst
===================================================================
--- libcxx/docs/DesignDocs/ABIVersioning.rst
+++ libcxx/docs/DesignDocs/ABIVersioning.rst
@@ -3,15 +3,21 @@
 Libc++ ABI stability
 ====================
 
-Libc++ aims to preserve stable ABI to avoid subtle bugs when code built to the old ABI
-is linked with the code build to the new ABI. At the same time, libc++ allows ABI-breaking
-improvements and bugfixes for the scenarios when ABI change is not a issue.
+Libc++ aims to preserve a stable ABI to avoid subtle bugs when code built under the old ABI
+is linked with code built under the new ABI. At the same time, libc++ wants to make
+ABI-breaking improvements and bugfixes in scenarios where the user doesn't mind ABI breaks.
 
-To support both cases, libc++ allows specifying the ABI version at the
-build time.  The version is defined with a cmake option
-LIBCXX_ABI_VERSION. Another option LIBCXX_ABI_UNSTABLE can be used to
-include all present ABI breaking features. These options translate
-into C++ macro definitions _LIBCPP_ABI_VERSION, _LIBCPP_ABI_UNSTABLE.
+To support both cases, libc++ allows specifying an ABI version at
+build time. The version is defined with CMake option
+``LIBCXX_ABI_VERSION``, which corresponds to the C++ macro ``_LIBCPP_ABI_VERSION``.
+Currently supported values are ``1`` (the stable default)
+and ``2`` (the unstable "next" version). At some point "ABI version 2" will be
+frozen and new unstable features will start being applied to version ``3``;
+but this has not happened yet.
 
-Any ABI-changing feature is placed under it's own macro, _LIBCPP_ABI_XXX, which is enabled
-based on the value of _LIBCPP_ABI_VERSION. _LIBCPP_ABI_UNSTABLE, if set, enables all features at once.
+Each ABI-changing feature is placed under its own C++ macro, ``_LIBCPP_ABI_XXX``,
+which is enabled based on the value of ``_LIBCPP_ABI_VERSION``.
+
+To always use the most cutting-edge, most unstable ABI, which enables all
+``_LIBCPP_ABI_XXX`` improvements, use the CMake option ``LIBCXX_ABI_UNSTABLE``,
+which corresponds to the C++ macro ``_LIBCPP_ABI_UNSTABLE``.