diff --git a/docs/src/main/asciidoc/extension-metadata.adoc b/docs/src/main/asciidoc/extension-metadata.adoc
index 0a0f6f88e01a1..4ee43cc70da03 100644
--- a/docs/src/main/asciidoc/extension-metadata.adoc
+++ b/docs/src/main/asciidoc/extension-metadata.adoc
@@ -11,6 +11,8 @@ include::_attributes.adoc[]
 Quarkus extensions are distributed as Maven JAR artifacts that application and other libraries may depend on. When a Quarkus application project is built, tested or edited using the Quarkus dev tools, Quarkus extension JAR artifacts will be identified on the application classpath by the presence of the Quarkus extension metadata files in them.
 This document describes the purpose of each Quarkus extension metadata file and its content.
 
+IMPORTANT: Two of the metadata files have the same name but different extensions, `quarkus-extension.yaml` and `quarkus-extension.properties`. It is easy to mix them up, be careful. You will usually edit the YAML file and track it in your SCM. While you _can_ manually manage the properties file, Quarkus will generated it at build if you don't.
+
 [[quarkus-extension-yaml]]
 == META-INF/quarkus-extension.yaml