diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -187,15 +187,50 @@
 Used LLVM-related Variables`_ below for information about commonly
 used variables that control features of LLVM and enabled subprojects.
 
+.. _cmake_build_type:
+
 **CMAKE_BUILD_TYPE**:STRING
-  Sets the build type for ``make``-based generators. Possible values are
-  Release, Debug, RelWithDebInfo and MinSizeRel. If you are using an IDE such as
-  Visual Studio, you should use the IDE settings to set the build type.
-  Be aware that Release and RelWithDebInfo use different optimization levels on
-  most platforms. Be aware that Release and
-  RelWithDebInfo use different optimization levels on most
-  platforms, and that the default value of ``LLVM_ENABLE_ASSERTIONS``
-  is affected.
+  This configures the optimization level for ``make`` or ``ninja`` builds.
+  The default ``CMAKE_BUILD_TYPE`` is set to ``Debug`` but you should
+  carefully read the list below to figure out what configuration matches
+  your use case the best.
+
+  Possible values:
+
+  **Release**
+    This enables the highest level of optimizations and disables
+    all debug information and assertions. This is the build type that most
+    users of LLVM and Clang want to use.
+
+  **Debug**
+    This build type enables debug information and disables most
+    optimizations. Builds using ``Debug`` will be siginficantly slower and
+    use a lot more diskspace then a ``Release`` build. When targetting
+    Linux/ELF It's not uncommon that your linker might run into issues
+    when linking ``Debug`` builds. It's recommended that ``Debug`` build
+    are linked with ``lld``, see the ``LLVM_ENABLE_LLD`` option.
+
+    Assertions will be enabled by default if you use this type and don't
+    specify ``LLVM_ENABLE_ASSERTIONS``.
+
+  **RelWithDebInfo**
+    This build type tries to give a balance between ``Release`` and
+    ``Debug`` builds. It enables most optimizations and also debug
+    information for debugging. This build is usually used when you want
+    to deploy something to production but you still need to debug it
+    in order to find a bug or problem. Size of binaries will be big and
+    linkers might have similar problems with this build as with ``Debug``.
+    These builds will default to disable assertions.
+
+  **MinSizeRel**
+    This build type will configure the build to be optimized for size
+    instead of speed. This should be used if you are tight on space and
+    speed of execution is not your primary concern. No debug information
+    is included by default in this configuration and assertions are turned
+    off.
+
+  If you are using an IDE such as Visual Studio or Xcode, you should use
+  the IDE settings to set the build type.
 
 **CMAKE_INSTALL_PREFIX**:PATH
   Path where LLVM will be installed when the "install" target is built.
diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst
--- a/llvm/docs/GettingStarted.rst
+++ b/llvm/docs/GettingStarted.rst
@@ -72,8 +72,11 @@
        pathname of where you want the LLVM tools and libraries to be installed
        (default ``/usr/local``).
 
-     * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
-       Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
+     * ``-DCMAKE_BUILD_TYPE=type`` --- Controls optimization level and debug information
+       of the build. Possible values are ``Release``, ``Debug``, ``MinSizeRel`` and
+       ``RelWithDebInfo``. The default value is ``Debug`` that fits people that want
+       to work on LLVM or with it's libraries. ``Release`` is a better fit for most
+       users of LLVM and Clang. For more detailed information see :ref:`CMAKE_BUILD_TYPE <cmake_build_type>`.
 
      * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
        (default is Yes for Debug builds, No for all other build types).
@@ -95,7 +98,7 @@
        option ``-j NN``, where ``NN`` is the number of parallel jobs, e.g. the
        number of available CPUs.
 
-   * For more information see `CMake <CMake.html>`__
+   * For more information see `CMake <CMake.html#>`__
 
    * If you get an "internal compiler error (ICE)" or test failures, see
      `below`_.
@@ -1186,15 +1189,19 @@
 
  * -DCMAKE_BUILD_TYPE
 
-    - Debug --- This is the default build type. This disables optimizations while
+    - **Debug** --- This is the default build type. This disables optimizations while
       compiling LLVM and enables debug info. On ELF-based platforms (e.g. Linux)
-      linking with debug info may consume a large amount of memory.
+      linking with debug info may consume a large amount of memory. This configuration
+      also consumes a lot more disk space, so if you have problems with how big
+      a build is, you should consider the ``Release`` type instead.
 
-    - Release --- Turns on optimizations and disables debug info. Combining the
+    - **Release** --- Turns on optimizations and disables debug info. Combining the
       Release build type with -DLLVM_ENABLE_ASSERTIONS=ON may be a good trade-off
       between speed and debugability during development, particularly for running
       the test suite.
 
+    For more information see :ref:`CMAKE_BUILD_TYPE <cmake_build_type>`.
+
  * -DLLVM_ENABLE_ASSERTIONS
    This option defaults to ON for Debug builds and defaults to OFF for Release
    builds. As mentioned in the previous option, using the Release build type and