diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc
index 5105f82b091..d2e0bf5fd77 100644
--- a/docs/reference/indices/put-mapping.asciidoc
+++ b/docs/reference/indices/put-mapping.asciidoc
@@ -1,7 +1,7 @@
 [[indices-put-mapping]]
 == Put Mapping
 
-The PUT mapping API allows you to provide type mappings while creating a new index, add a new type to an existing index, or add new
+The PUT mapping API allows you to add a new type to an existing index, or add new
 fields to an existing type:
 
 [source,js]
@@ -62,6 +62,11 @@ PUT /{index}/_mapping/{type}
 * `{body}` contains the mapping changes that should be applied.
 
 
+NOTE: When updating the `_default_` mapping with the
+<<indices-put-mapping,PUT mapping>> API, the new mapping is not merged with
+the existing mapping.  Instead, the new `_default_` mapping replaces the
+existing one.
+
 [[updating-field-mappings]]
 [float]
 === Updating field mappings
diff --git a/docs/reference/mapping/dynamic/default-mapping.asciidoc b/docs/reference/mapping/dynamic/default-mapping.asciidoc
index 8fcc9114dfc..de96667b7e3 100644
--- a/docs/reference/mapping/dynamic/default-mapping.asciidoc
+++ b/docs/reference/mapping/dynamic/default-mapping.asciidoc
@@ -32,6 +32,11 @@ PUT my_index
 <2> The `user` type inherits the settings from `_default_`.
 <3> The `blogpost` type overrides the defaults and enables the <<mapping-all-field,`_all`>> field.
 
+NOTE: When updating the `_default_` mapping with the
+<<indices-put-mapping,PUT mapping>> API, the new mapping is not merged with
+the existing mapping.  Instead, the new `_default_` mapping replaces the
+existing one.
+
 While the `_default_` mapping can be updated after an index has been created,
 the new defaults will only affect mapping types that are created afterwards.