diff --git a/libcxx/docs/DesignDocs/ABIVersioning.rst b/libcxx/docs/DesignDocs/ABIVersioning.rst
--- a/libcxx/docs/DesignDocs/ABIVersioning.rst
+++ b/libcxx/docs/DesignDocs/ABIVersioning.rst
@@ -3,15 +3,22 @@
 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``.
+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 ABI-breaking changes 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.
+To always use the most cutting-edge, most unstable ABI (which is currently ``2``
+but at some point will become ``3``), set the CMake option ``LIBCXX_ABI_UNSTABLE``.
+
+Internally, each ABI-changing feature is placed under its own C++ macro,
+``_LIBCPP_ABI_XXX``. These macros' definitions are controlled by the C++ macro
+``_LIBCPP_ABI_VERSION``, which is controlled by the ``LIBCXX_ABI_VERSION`` set
+at build time. Libc++ does not intend users to interact with these C++ macros
+directly.