diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc
index e54902fe2b7f..45d3d8e374f9 100644
--- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc
+++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc
@@ -971,7 +971,8 @@ The `SpringApplication` class automatically supports YAML as an alternative to p
 
 NOTE: If you use "`Starters`", SnakeYAML is automatically provided by `spring-boot-starter`.
 
-
+WARNING: YAML files cannot be loaded by using the `@PropertySource` or `@TestPropertySource` annotations.
+So, in the case that you need to load values that way, you need to use a properties file.
 
 ==== Mapping YAML to Properties
 YAML documents need to be converted from their hierarchical format to a flat structure that can be used with the Spring `Environment`.
@@ -1032,34 +1033,6 @@ The `YamlPropertiesFactoryBean` loads YAML as `Properties` and the `YamlMapFacto
 You can also use the `YamlPropertySourceLoader` class if you want to load YAML as a Spring `PropertySource`.
 
 
-
-[[boot-features-external-config-yaml-shortcomings]]
-==== YAML Shortcomings
-YAML files cannot be loaded by using the `@PropertySource` annotation.
-So, in the case that you need to load values that way, you need to use a properties file.
-
-Using the multi-document YAML syntax in profile-specific YAML files can lead to unexpected behavior.
-For example, consider the following config in a file:
-
-.application-dev.yml
-[source,yaml,indent=0]
-----
-	server.port: 8000
-	---
-	spring.config.activate.on-profile: "!test"
-	mypassword: "secret"
-----
-
-If you run the application with the argument `--spring.profiles.active=dev` you might expect `mypassword` to be set to "`secret`", but this is not the case.
-
-The nested document will be filtered because the main file is named `application-dev.yml`.
-It is already considered to be profile-specific, and nested documents will be ignored.
-
-TIP: We recommend that you don't mix profile-specific YAML files and multiple YAML documents.
-Stick to using only one of them.
-
-
-
 [[boot-features-external-config-random-values]]
 === Configuring Random Values
 The `RandomValuePropertySource` is useful for injecting random values (for example, into secrets or test cases).